Pressable

Author: m-bert

packages/docs-gesture-handler/docs/components/pressable.mdx

@@ -7,133 +7,237 @@ sidebar_label: Pressable
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import GifGallery from '@site/components/GifGallery';
 
-<GifGallery>
-  <img src={useBaseUrl('gifs/pressable.gif')} width="70%" />
-</GifGallery>
-
 :::info
 This component is a drop-in replacement for the `Pressable` component.
 :::
 
-`Pressable` is a component that can detect various stages of tap, press, and hover interactions on any of its children.
+<GifGallery>
+  <img src={useBaseUrl('gifs/pressable.gif')} width="70%" />
+</GifGallery> 
 
-### Usage:
+`Pressable` is a component that can detect various stages of tap, press, and hover interactions on any of its children.
 
-To use `Pressable`, import it in the following way:
+To use `Pressable`, ensure that your app is wrapped in `GestureHandlerRootView` and import it as follows:
 
-```js
+```ts
 import { Pressable } from 'react-native-gesture-handler';
 ```
 
 ## Properties
 
-### `children`
+### children
+
+```ts
+children?:
+  | React.ReactNode
+  | ((state: PressableStateCallbackType) => React.ReactNode);
+```
+
+Either children or a render prop that receives a boolean reflecting whether the component is currently pressed.
+
+### style
+
+```ts
+style?:
+  | StyleProp<ViewStyle>
+  | ((state: PressableStateCallbackType) => StyleProp<ViewStyle>);
+```
+
+Either view styles or a function that receives a boolean reflecting whether the component is currently pressed and returns view styles.
+
+### onPress
+
+```ts
+onPress?: null | ((event: PressableEvent) => void);
+```
+
+Called after [`onPressOut`](#onpressout) when a single tap gesture is detected. Details about the event object can be found in the [PressableEvent](#pressableevent) section below.
+
+### onPressIn
+
+```ts
+onPressIn?: null | ((event: PressableEvent) => void);
+```
+
+Called before `onPress` when a touch is engaged. Details about the event object can be found in the [PressableEvent](#pressableevent) section below.
+
+### onPressOut
+
+```ts
+onPressOut?: null | ((event: PressableEvent) => void);
+```
+
+Called before `onPress` when a touch is released (before [`onPress`](#onpress)). Details about the event object can be found in the [PressableEvent](#pressableevent) section below.
 
-either children or a render function that receives a boolean reflecting whether
-the component is currently pressed.
+### onLongPress
 
-### `style`
+```ts
+onLongPress?: null | ((event: PressableEvent) => void);
+```
+
+Called immediately after pointer has been down for at least [`delayLongPress`](#delaylongpress) milliseconds.
 
-either view styles or a function that receives a boolean reflecting whether
-the component is currently pressed and returns view styles.
+After `onLongPress` has been called, [`onPressOut`](#onpressout) will be called as soon as the pointer is lifted and [`onPress`](#onpress) will not be called at all.
 
-### `onPress`
+### cancelable
+
+```ts
+cancelable?: null | boolean;
+```
 
-called after `onPressOut` when a single tap gesture is detected.
+Whether a press gesture can be interrupted by a parent gesture such as a scroll event. Defaults to `true`.
+
+### onHoverIn (Web only)
+
+```ts
+onHoverIn?: null | ((event: PressableEvent) => void);
+```
 
-### `onPressIn`
+Called when pointer is hovering over the element.
 
-called before `onPress` when a touch is engaged.
+### onHoverOut (Web only)
+
+```ts
+onHoverOut?: null | ((event: PressableEvent) => void);
+```
+
+Called when pointer stops hovering over the element.
+
+### delayHoverIn (Web only)
+
+```ts
+delayHoverIn?: number | null;
+```
 
-### `onPressOut`
+Duration to wait after hover in before calling `onHoverIn`.
 
-called before `onPress` when a touch is released.
+### delayHoverOut (Web only)
 
-### `onLongPress`
+```ts
+delayHoverOut?: number | null;
+```
 
-called immediately after pointer has been down for at least `delayLongPress` milliseconds (`500` ms by default).
+Duration to wait after hover out before calling `onHoverOut`.
 
-After `onLongPress` has been called, `onPressOut` will be called as soon as the pointer is lifted and `onPress` will not be called at all.
+### delayLongPress
 
-### `cancelable`
+```ts
+delayLongPress?: null | number;
+```
 
-whether a press gesture can be interrupted by a parent gesture such as a scroll event. Defaults to `true`.
+Duration (in milliseconds) from `onPressIn` before `onLongPress` is called. Default value is `500` ms.
 
-### `onHoverIn` (Web only)
+### disabled
 
-called when pointer is hovering over the element.
+```ts
+disabled?: null | boolean;
+```
 
-### `onHoverOut` (Web only)
+Whether the `Pressable` behavior is disabled.
 
-called when pointer stops hovering over the element.
+### hitSlop (Android & iOS only)
 
-### `delayHoverIn` (Web only)
+```ts
+hitSlop?: null | Insets | number;
+```
 
-duration to wait after hover in before calling `onHoverIn`.
+Additional distance outside of the view in which a press is detected and [`onPressIn`](#onpressin) is triggered.
 
-### `delayHoverOut` (Web only)
+The `Insets` type is essentially the same as [`Rect`](https://reactnative.dev/docs/rect).
 
-duration to wait after hover out before calling `onHoverOut`.
+### pressRetentionOffset (Android & iOS only)
 
-### `delayLongPress`
+```ts
+pressRetentionOffset?: null | Insets | number;
+```
 
-duration (in milliseconds) from `onPressIn` before `onLongPress` is called.
+Additional distance outside of the view (or [`hitSlop`](#hitslop) if present) in which a touch is considered a
+press before [`onPressOut`](#onpressout) is triggered.
 
-### `disabled`
+The `Insets` type is essentially the same as [`Rect`](https://reactnative.dev/docs/rect).
 
-whether the `Pressable` behavior is disabled.
+### android_disableSound (Android only)
 
-### `hitSlop` (Android & iOS only)
+```ts
+android_disableSound?: null | boolean;
+```
 
-additional distance outside of the view in which a press is detected and `onPressIn` is triggered.
+If `true`, doesn't play system sound on touch.
 
-Accepts values of type `number` or [`Rect`](https://reactnative.dev/docs/rect)
+### android_ripple (Android only)
 
-### `pressRetentionOffset` (Android & iOS only)
+```ts
+android_ripple?: null | PressableAndroidRippleConfig;
+```
 
-additional distance outside of the view (or `hitSlop` if present) in which a touch is considered a
-press before `onPressOut` is triggered.
+Enables the Android [ripple](https://developer.android.com/reference/android/graphics/drawable/RippleDrawable) effect and configures its color, radius and other parameters.
 
-Accepts values of type `number` or [`Rect`](https://reactnative.dev/docs/rect)
+Accepts values of type [`RippleConfig`](https://reactnative.dev/docs/pressable#rippleconfig).
 
-### `android_disableSound` (Android only)
+### testOnly_pressed
 
-if `true`, doesn't play system sound on touch.
+```ts
+testOnly_pressed?: null | boolean;
+```
 
-### `android_ripple` (Android only)
+Used only for documentation or testing (e.g. snapshot testing).
 
-enables the Android ripple effect and configures its color, radius and other parameters.
+### unstable_pressDelay
 
-Accepts values of type [`RippleConfig`](https://reactnative.dev/docs/pressable#rippleconfig)
+```ts
+unstable_pressDelay?: number | undefined;
+```
 
-### `testOnly_pressed`
+Duration (in milliseconds) to wait after press down before calling [`onPressIn`](#onpressin).
 
-used only for documentation or testing (e.g. snapshot testing).
+## PressableEvent
 
-### `unstable_pressDelay`
+All `Pressable` callbacks receive an event object as a parameter, which is of type `PressableEvent` and has the following structure:
 
-duration (in milliseconds) to wait after press down before calling `onPressIn`.
+```ts
+export type PressableEvent = { nativeEvent: InnerPressableEvent };
 
-### Example:
+export type InnerPressableEvent = {
+  changedTouches: InnerPressableEvent[];
+  identifier: number;
+  locationX: number;
+  locationY: number;
+  pageX: number;
+  pageY: number;
+  target: number;
+  timestamp: number;
+  touches: InnerPressableEvent[];
+  force?: number;
+};
+```
 
-See the full [pressable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/new_api/pressable/index.tsx) from `GestureHandler` example app.
+## Example
 
-import GestureStateFlowExample from '@site/src/examples/GestureStateFlowExample';
+See the full example in [Gesture Handler repository](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/legacy/v2_api/pressable/index.tsx).
 
-```js
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[5, 20]}
+src={`
 import { View, Text, StyleSheet } from 'react-native';
-import { Pressable } from 'react-native-gesture-handler';
+import {
+  GestureHandlerRootView,
+  Pressable,
+} from 'react-native-gesture-handler';
 
 export default function Example() {
   return (
-    <Pressable
-      style={({ pressed }) => (pressed ? styles.highlight : styles.pressable)}
-      hitSlop={20}
-      pressRetentionOffset={20}>
-      <View style={styles.textWrapper}>
-        <Text style={styles.text}>Pressable!</Text>
-      </View>
-    </Pressable>
+    <GestureHandlerRootView>
+      <Pressable
+        style={({ pressed }) => (pressed ? styles.highlight : styles.pressable)}
+        hitSlop={20}
+        pressRetentionOffset={20}>
+        <View style={styles.textWrapper}>
+          <Text style={styles.text}>Pressable!</Text>
+        </View>
+      </Pressable>
+    </GestureHandlerRootView>
   );
 }
 
@@ -159,4 +263,5 @@ const styles = StyleSheet.create({
     color: 'black',
   },
 });
-```
+
+`}/>

packages/react-native-gesture-handler/src/components/Pressable/PressableProps.tsx

@@ -75,12 +75,12 @@ interface CommonPressableProps
   extends AccessibilityProps,
     Omit<ViewProps, 'children' | 'style' | 'hitSlop'> {
   /**
-   * Called when the hover is activated to provide visual feedback.
+   * Called when pointer is hovering over the element.
    */
   onHoverIn?: null | ((event: PressableEvent) => void);
 
   /**
-   * Called when the hover is deactivated to undo visual feedback.
+   * Called when pointer stops hovering over the element.
    */
   onHoverOut?: null | ((event: PressableEvent) => void);
 
@@ -100,7 +100,7 @@ interface CommonPressableProps
   onPressOut?: null | ((event: PressableEvent) => void);
 
   /**
-   * Called when a long-tap gesture is detected.
+   * Called immediately after pointer has been down for at least `delayLongPress` milliseconds (`500` ms by default).
    */
   onLongPress?: null | ((event: PressableEvent) => void);
 
@@ -140,7 +140,7 @@ interface CommonPressableProps
   delayHoverOut?: number | null;
 
   /**
-   * Duration (in milliseconds) from `onPressIn` before `onLongPress` is called.
+   * Duration (in milliseconds) from `onPressIn` before `onLongPress` is called. Default value is `500` ms.
    */
   delayLongPress?: null | number;