[Docs] Document Touchable hover callbacks

[j-piasecki]

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.

Test plan

yarn start in packages/docs-gesture-handler.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7101e888-2880-4fc7-a13a-bdd225818536

📥 Commits

Reviewing files that changed from the base of the PR and between 9089315 and 3c664a6.

📒 Files selected for processing (1)

• packages/docs-gesture-handler/docs/components/touchable.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/docs-gesture-handler/docs/components/touchable.mdx

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Updated Touchable press, long-press, and hover callback documentation.
  • Clarified that callbacks receive ButtonEvent data, including pointer coordinates, state, count, and type.
  • Added guidance for handling hover behavior, pointer filtering, disabled states, platform differences, and tvOS focus.
  • Documented onHoverIn and onHoverOut callbacks.
  • Clarified callback signatures and event-handling expectations for more consistent interaction handling.

Walkthrough

The Touchable documentation updates press and long-press callbacks to use ButtonEvent and adds documentation for onHoverIn and onHoverOut, including pointer filtering and hover behavior.

Changes

Touchable callback documentation

Layer / File(s)	Summary
Press event callbacks packages/docs-gesture-handler/docs/components/touchable.mdx	onPressIn, onPressOut, onPress, and onLongPress now document ButtonEvent payloads with pointer state, coordinates, count, and type.
Hover callbacks packages/docs-gesture-handler/docs/components/touchable.mdx	The documentation adds onHoverIn and onHoverOut with coordinate-based ButtonEvent payloads and pointer filtering details.

Possibly related PRs

• software-mansion/react-native-gesture-handler#4394: Updates the v3 button and Touchable API in a different file.
• software-mansion/react-native-gesture-handler#4396: Implements callback types and hover props documented by this PR.
• software-mansion/react-native-gesture-handler#4397: Implements Touchable hover event types and delegate behavior.

Suggested reviewers: m-bert

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the pull request's main change: documenting Touchable hover callbacks.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

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

Parsing error: ESLint was configured to run on <tsconfigRootDir>/packages/docs-gesture-handler/docs/components/touchable.mdx using parserOptions.project: /tsconfig.json
The extension for the file (.mdx) is non-standard. You should add parserOptions.extraFileExtensions to your config.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR updates the Gesture Handler 3 docs for the new Touchable component by documenting onHoverIn / onHoverOut, including detailed platform-specific behavior (pairing semantics, disabled interactions, press-drag behavior, tvOS focus-driven hover, and unmount/detach behavior).

Changes:

• Add new onHoverIn and onHoverOut prop sections to the Touchable documentation.
• Describe non-obvious behavioral details and platform differences for hover callbacks.
• Provide event/type signatures for the new hover callbacks via CollapsibleCode.

Suppressed comments (2)

packages/docs-gesture-handler/docs/components/touchable.mdx:505

• Same as above: the public ButtonEvent type uses pointerType: number (not PointerType), so this snippet should match that to avoid contradicting the exported TS types.

    absoluteX: number;
    absoluteY: number;
    numberOfPointers: number;
    pointerType: PointerType;
}

packages/docs-gesture-handler/docs/components/touchable.mdx:486

• This page now documents hover callbacks using ButtonEvent, but the existing onPressIn/onPressOut/onPress sections above still show GestureEvent<NativeHandlerData>. In the current v3 API, TouchableProps types all of these as (event: ButtonEvent) => void, so the page mixes two incompatible signatures.

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.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/docs-gesture-handler/docs/components/touchable.mdx`:
- Around line 378-386: Wrap every ButtonEvent object type in Readonly<> to
preserve the exported event contract. Apply this to the onPressIn declaration in
packages/docs-gesture-handler/docs/components/touchable.mdx lines 378-386, and
likewise update the onPressOut declaration at lines 408-416, onPress at lines
438-446, onLongPress at lines 468-476, onHoverIn at lines 498-506, and
onHoverOut at lines 528-536.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f51a769a-f0f6-4c1f-8eca-9dc32fad3e5d

📥 Commits

Reviewing files that changed from the base of the PR and between 62ca5fa and 886f0db.

📒 Files selected for processing (1)

• packages/docs-gesture-handler/docs/components/touchable.mdx

[m-bert]

Tbh I don't like the fact that this long hover explanation is below onHoverOut. I mean I know that it is in the right section, but some parts sound like they belong to onHoverIn rather than onHoverOut. Maybe we could duplicate it? Also this is now one big section amid prop descriptions, while it covers both props at the same time.

[j-piasecki]

@m-bert actually, I'm not sure whether describing it in such detail is needed (contrasts with the existing sections). I trimmed it in 9089315 and removed tvOS block moved the tvOS note to a :::note block. Let me know what you think.