From 3c664a6e422b28dc77fe613f7b8397c23974e805 Mon Sep 17 00:00:00 2001
From: Jakub Piasecki <jakub.piasecki@swmansion.com>
Date: Thu, 6 Aug 2026 10:52:13 +0200
Subject: [PATCH] [Docs] Document Touchable hover callbacks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Description

Documents `onHoverIn`/`onHoverOut` on the `Touchable` page, together
with the behaviour that isn't obvious from the signature: how the two
pair up, what `disabled` does to an open hover, which platforms report
the crossings during a press, tvOS driving hover from focus, and hover
state not surviving an unmount or a detach.

Also refreshes the press callbacks on the same page, which still
described the pre-#4342/#4343 signature. `onPress`, `onPressIn` and
`onPressOut` take a `ButtonEvent` rather than a
`GestureEvent<NativeHandlerData>`, and `onLongPress` takes an event at
all — the old snippets additionally listed a `handlerTag` field that
`ButtonEvent` does not carry, and omitted `x`/`y`/`absoluteX`/`absoluteY`.
Leaving them alone would have put contradictory signatures directly
above the new hover blocks.

## Test plan

`yarn start` in `packages/docs-gesture-handler`.
---
 .../docs/components/touchable.mdx             | 120 +++++++++++++++---
 1 file changed, 105 insertions(+), 15 deletions(-)

diff --git a/packages/docs-gesture-handler/docs/components/touchable.mdx b/packages/docs-gesture-handler/docs/components/touchable.mdx
index 660d06a8d5..057ff44541 100644
--- a/packages/docs-gesture-handler/docs/components/touchable.mdx
+++ b/packages/docs-gesture-handler/docs/components/touchable.mdx
@@ -373,13 +373,16 @@ label="Show composed types definitions"
 expandedLabel="Hide composed types definitions"
 lineBounds={[0, 1]}
 src={`
-onPressIn?: (e: GestureEvent<NativeHandlerData>) => void;
+onPressIn?: (e: ButtonEvent) => void;
 
-type GestureEvent<NativeHandlerData> = {
-    handlerTag: number;
+type ButtonEvent = {
+    pointerInside: boolean;
+    x: number;
+    y: number;
+    absoluteX: number;
+    absoluteY: number;
     numberOfPointers: number;
     pointerType: PointerType;
-    pointerInside: boolean;
 }
 
 enum PointerType {
@@ -400,13 +403,16 @@ label="Show composed types definitions"
 expandedLabel="Hide composed types definitions"
 lineBounds={[0, 1]}
 src={`
-onPressOut?: (e: GestureEvent<NativeHandlerData>) => void;
+onPressOut?: (e: ButtonEvent) => void;
 
-type GestureEvent<NativeHandlerData> = {
-    handlerTag: number;
+type ButtonEvent = {
+    pointerInside: boolean;
+    x: number;
+    y: number;
+    absoluteX: number;
+    absoluteY: number;
     numberOfPointers: number;
     pointerType: PointerType;
-    pointerInside: boolean;
 }
 
 enum PointerType {
@@ -427,13 +433,16 @@ label="Show composed types definitions"
 expandedLabel="Hide composed types definitions"
 lineBounds={[0, 1]}
 src={`
-onPress?: (e: GestureEvent<NativeHandlerData>) => void;
+onPress?: (e: ButtonEvent) => void;
 
-type GestureEvent<NativeHandlerData> = {
-    handlerTag: number;
+type ButtonEvent = {
+    pointerInside: boolean;
+    x: number;
+    y: number;
+    absoluteX: number;
+    absoluteY: number;
     numberOfPointers: number;
     pointerType: PointerType;
-    pointerInside: boolean;
 }
 
 enum PointerType {
@@ -449,12 +458,93 @@ Triggered when the button gets pressed (analogous to `onPress` in `Pressable` fr
 
 ### onLongPress
 
-```ts
-onLongPress?: () => void;
-```
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 1]}
+src={`
+onLongPress?: (e: ButtonEvent) => void;
+
+type ButtonEvent = {
+    pointerInside: boolean;
+    x: number;
+    y: number;
+    absoluteX: number;
+    absoluteY: number;
+    numberOfPointers: number;
+    pointerType: PointerType;
+}
+
+enum PointerType {
+    TOUCH,
+    STYLUS,
+    MOUSE,
+    KEY,
+    OTHER,
+}
+`}/>
 
 Triggered when the button gets pressed for at least [`delayLongPress`](#delaylongpress) milliseconds.
 
+### onHoverIn
+
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 1]}
+src={`
+onHoverIn?: (e: ButtonEvent) => void;
+
+type ButtonEvent = {
+    pointerInside: boolean;
+    x: number;
+    y: number;
+    absoluteX: number;
+    absoluteY: number;
+    numberOfPointers: number;
+    pointerType: PointerType;
+}
+
+enum PointerType {
+    TOUCH,
+    STYLUS,
+    MOUSE,
+    KEY,
+    OTHER,
+}
+`}/>
+
+Triggered when a non-touch pointer - a mouse, a trackpad cursor, or a hovering stylus - moves over the button (analogous to `onHoverIn` in `Pressable` from RN core). Touch pointers never report hover.
+
+### onHoverOut
+
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 1]}
+src={`
+onHoverOut?: (e: ButtonEvent) => void;
+
+type ButtonEvent = {
+    pointerInside: boolean;
+    x: number;
+    y: number;
+    absoluteX: number;
+    absoluteY: number;
+    numberOfPointers: number;
+    pointerType: PointerType;
+}
+
+enum PointerType {
+    TOUCH,
+    STYLUS,
+    MOUSE,
+    KEY,
+    OTHER,
+}
+`}/>
+
+Triggered when the hovering pointer leaves the button (analogous to `onHoverOut` in `Pressable` from RN core).
 
 ### delayLongPress