Migrate attachment carousel and MultiGestureCanvas gestures to Gesture Handler 3 hooks by collectioneur · Pull Request #103461 · Expensify/App

collectioneur · 2026-10-08T12:44:55Z

Explanation of Change

Part of the migration from the deprecated Gesture Handler 3 builder API (Gesture.*, GestureType, Legacy* types) to the hook API (#102782). The migration is split into independent PRs by feature area. This one covers the attachment carousel and MultiGestureCanvas.

Mechanical changes: Gesture.*() builders → use*Gesture() hooks, onStart/onChange/onEnd → onActivate/onUpdate/onDeactivate, state.activate()/fail() → GestureStateManager.activate()/fail(evt.handlerTag), success in onFinalize → !event.canceled.

Non-obvious parts:

No gesture refs in the hook API. Relations take gesture objects, so the web carousel passes its pan through the pager context as pagerGesture (used by Lightbox, PDFView, MultiGestureIcon). pagerRef now only tells an attachment it's inside a carousel. On native it never carried a real relation (PagerView has no handlerTag).
Creation order in MultiGestureCanvas. A gesture can only reference gestures created before it, so the pan is created first and the taps declare the simultaneous relation with it (simultaneous relations are symmetric). The relations and the Simultaneous(pinch, Race(taps, pan)) composition are unchanged.
Local hooks renamed. usePanGesture / usePinchGesture / useTapGestures in MultiGestureCanvas are now useCanvasPanGesture / useCanvasPinchGesture / useCanvasTapGestures, so they no longer shadow the Gesture Handler hooks. The Gesture Handler hooks are called by their own names, and the worklets Babel plugin turns their callbacks into worklets automatically (checked on the transformed native output: all 14 callbacks are worklets).
React Compiler. Without refs read during render, MultiGestureCanvas and AttachmentCarouselView now compile with both Babel and OXC, so the React.memo workaround on AttachmentCarouselView is removed.

Fixed Issues

$ #102782
PROPOSAL: N/A

Tests

iOS/Android:

Open a chat with several image attachments and open one.
Pinch to zoom and verify it zooms around the fingers and bounces back past the limits.
While zoomed, pan in all directions and verify the image follows the finger, keeps moving after a fling, snaps back inside the bounds, and a horizontal swipe pans instead of switching attachments.
Double tap a point to zoom in around it and double tap again to zoom out. Not zoomed, swipe left / right to switch attachments (a short slow swipe snaps back).

iOS/Android:

Tap + in the Concierge box on Home and pick two images and a .txt file at once. In the preview, verify swiping switches between the files.

IOS/Android:

Outside the carousel and with a mouse: open a user's avatar full screen, and expand a chart from a chat message (e.g. a Concierge reply with a chart). Pinch, pan, double tap and swipe down, and verify each works.

Android:

PDFs and non-previewable files: open a PDF in a carousel with other attachments.
Verify vertical scrolling doesn't switch attachments, a horizontal swipe does, and once the PDF is zoomed horizontal swipes no longer switch.

Web:
4. open an image attachment with siblings and verify the arrows and the keyboard arrow keys switch attachments.

Note: pinch freezing at the max/min zoom on Android is a known bug on main (#103648), not caused by this PR.

Verify that no errors appear in the JS console

Offline tests

QA Steps

Same as tests

Verify that no errors appear in the JS console

PR Author Checklist

Screenshots/Videos

Android: Native

android_attachment_compressed.mp4

Android: mWeb Chrome

Screen.Recording.2026-10-22.at.15.46.34.mov

iOS: Native

ios_attachmentCarousel_compressed.mp4

iOS: mWeb Safari

Uploading Screen Recording 2026-10-22 at 15.32.39.mov…

MacOS: Chrome / Safari

web_attachment.mov

…e Handler 3 hooks Move the attachment carousel (web pan and native pager), the Android PDF pager pan and MultiGestureCanvas (pinch, pan, single and double tap) from the deprecated builder API to the hook API. Gesture refs don't exist in the hook API, so the web carousel passes its pan gesture through the pager context as pagerGesture instead of the gesture ref in pagerRef. pagerRef now points to the pager itself and only tells the attachment it is rendered inside a carousel. In MultiGestureCanvas the pan gesture is created before the taps, because the single tap waits for it to fail; the taps declare the simultaneous relation with the pan instead, which is symmetric. Without the refs read during render, AttachmentCarouselView and MultiGestureCanvas now compile with React Compiler, so the React.memo workaround is dropped and the seatbelt baseline is tightened.

codecov · 2026-10-08T12:48:34Z

Codecov Report

✅ Changes either increased or maintained existing code coverage, great job!

Files with missing lines	Coverage Δ
...nts/Attachments/AttachmentCarousel/Pager/index.tsx	`100.00% <100.00%> (ø)`
...tachments/MultiGestureIcon/useIconCarouselPager.ts	`0.00% <ø> (ø)`
src/components/Lightbox/index.tsx	`90.80% <ø> (ø)`
src/components/PDFView/index.tsx	`0.00% <ø> (ø)`
.../components/Attachments/MultiGestureIcon/index.tsx	`0.00% <0.00%> (ø)`
...AttachmentView/AttachmentViewPdf/index.android.tsx	`0.00% <0.00%> (ø)`
...mponents/MultiGestureCanvas/useCanvasPanGesture.ts	`7.81% <14.28%> (ø)`
...onents/MultiGestureCanvas/useCanvasPinchGesture.ts	`2.04% <14.28%> (ø)`
src/components/MultiGestureCanvas/index.tsx	`1.56% <0.00%> (+0.35%)`	⬆️
...ponents/MultiGestureCanvas/useCanvasTapGestures.ts	`3.12% <11.11%> (ø)`
... and 1 more
... and 19 files with indirect coverage changes

OSBotify tightens the baseline after merge, so editing it here only causes conflicts between the migration PRs.

collectioneur · 2026-10-16T15:37:45Z

@codex review

chatgpt-codex-connector · 2026-10-16T15:38:05Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-16T16:44:31.487470Z	`14f6eec`	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

chatgpt-codex-connector · 2026-10-16T15:53:48Z

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 6cc35c615a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

melvin-bot · 2026-10-16T16:25:21Z

@QichenZhu Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

mikolajpochec

LGTM! I'm leaving two comments. Nothing blocking

JmillsExpensify

No product review required.

collectioneur · 2026-10-19T14:34:45Z

@QichenZhu could you please test this one too? 🙏

MelvinBot · 2026-10-21T08:28:19Z

I found no accessibility issues in this PR. It only changes how the gestures are wired up (the Gesture Handler 3 hook API). It does not touch any accessibility labels, roles, focus order, keyboard handling, or the carousel arrow buttons.

What I checked

No accessibility props changed. None of the 13 changed files add, remove, or change accessibilityLabel, role, accessible, focus, or keyboard handlers. The carousel arrows and arrow-key navigation are untouched in AttachmentCarouselView/index.tsx:247-266.
Arrow visibility on tap behaves the same. The single tap toggles the arrows (the main non-gesture way to switch attachments). It now checks evt.canceled instead of !success in useCanvasTapGestures.ts:183. In react-native-gesture-handler 3.3.0, canceled is true for both the FAILED and CANCELLED states. That matches the old success flag, so failed taps still don't toggle the arrows.
Carousel detection on web still works. pagerRef now points to scrollRef on web. PDFView still gets a truthy isUsedInCarousel from it.
The gesture setup is unchanged. The composition (Simultaneous(pinch, Race(taps, pan))) and the enabled: canUseTouchScreen guard on the web pan are the same as before. Screen-reader users don't trigger these gestures directly, because VoiceOver and TalkBack handle touches first.

Already on main (not caused by this PR): Pinch-to-zoom and double-tap-to-zoom have no button alternative, as WCAG 2.5.1 (Pointer Gestures) asks. Attachment switching does have one: the arrows and the arrow keys.

I reviewed only the code. I didn't run the changes in the app.

QichenZhu · 2026-10-21T09:56:07Z

Reviewer Checklist

Screenshots/Videos

Android: HybridApp

android-native.mp4

android-native.webm

Android: mWeb Chrome

android-web.mp4

android-web.webm

iOS: HybridApp

ios-native.mp4

ios-native.mov

iOS: mWeb Safari

ios-web.mp4

ios-web.mov

MacOS: Chrome / Safari

mac-web.mov

QichenZhu · 2026-10-21T10:01:39Z

NAB: on Android mWeb, in a chat with at least two image attachments, open the second one, double tap to zoom in, then immediately swipe right. The carousel stops responding to tapping and panning.

nab-1.mov

QichenZhu · 2026-10-21T10:03:13Z

NAB: on Android mWeb, you need to swipe right on a PDF several times to switch to the previous attachment.

nab-2.webm

…s the content after pinch on web

QichenZhu · 2026-10-22T08:33:31Z

Please let me know when this is ready for re-review.

collectioneur · 2026-10-22T13:52:09Z

@QichenZhu, the PR is ready for re-review. The problem was that the new hooks API changed the order of applying gestures on the web, which is why the Pan onDeactivated wasn't applied on mWeb iOS. The fix was to declare pitch before pan, and now everything works. I also added videos for mWeb iOS and Android 😄

QichenZhu

Thanks!

mountiny

Thanks

github-actions · 2026-10-23T10:37:02Z

🚧 mountiny has triggered a test Expensify/App build. You can view the workflow run here.

github-actions · 2026-10-23T10:41:35Z

🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
Built from App PR #103461.

Android 🤖	iOS 🍎
https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-android-Adhoc-dd8a925e-bf46249-767677e796c342884f46ba8644e1a797cdb9d8e6/index.html	https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-ios-device-AdHoc-dd8a925e-bf46249-e7bef24c3f461d43c438dd9313c8a81265f58c54/index.html

Web 🕸️
https://103461.pr-testing.expensify.com

👀 View the workflow run that generated this build 👀

OSBotify · 2026-10-23T10:45:50Z

✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release.

OSBotify · 2026-10-23T17:13:47Z

🚀 Deployed to staging by https://github.com/mountiny in version: 9.5.20-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

MelvinBot · 2026-10-23T17:17:42Z

No help site update is needed. This PR is an internal migration of attachment carousel and zoom gestures to the Gesture Handler 3 hook API, and it doesn't change any feature, label, or workflow that users see.

view run

melvin-bot Bot assigned collectioneur Oct 8, 2026

collectioneur added 4 commits October 9, 2026 13:08

Revert eslint-seatbelt baseline changes

368ec0b

OSBotify tightens the baseline after merge, so editing it here only causes conflicts between the migration PRs.

Merge branch 'main' into collectioneur/gesture-handler-hooks-attachments

c358326

Merge branch 'main' into collectioneur/gesture-handler-hooks-attachments

b02cf76

rename our custom hooks

6cc35c6

rename lines in tsv

14f6eec

collectioneur marked this pull request as ready for review October 16, 2026 16:25

collectioneur requested review from a team as code owners October 16, 2026 16:25

melvin-bot Bot requested review from QichenZhu and removed request for a team October 16, 2026 16:25

melvin-bot Bot requested review from JmillsExpensify and removed request for a team October 16, 2026 16:25

mikolajpochec reviewed Oct 16, 2026

View reviewed changes

Comment thread src/components/Attachments/AttachmentCarousel/AttachmentCarouselView/index.tsx Outdated

Comment thread src/components/MultiGestureCanvas/useCanvasPinchGesture.ts Outdated

JmillsExpensify reviewed Oct 16, 2026

View reviewed changes

collectioneur added 2 commits October 19, 2026 12:27

remove worklet directive when it's not needed

84a6f32

Merge branch 'main' into collectioneur/gesture-handler-hooks-attachments

1feb8f1

This comment was marked as resolved.

Sign in to view

collectioneur added 2 commits October 21, 2026 17:37

Create the pinch gesture before the pan gesture so that pan re-center…

e2b022d

…s the content after pinch on web

Merge branch 'main' into collectioneur/gesture-handler-hooks-attachments

fe892c3

collectioneur added 3 commits October 22, 2026 14:34

Merge branch 'main' into collectioneur/gesture-handler-hooks-attachments

d2f6765

fix types

a7546bf

fix test

89f17e0

QichenZhu approved these changes Oct 23, 2026

View reviewed changes

melvin-bot Bot requested a review from mountiny October 23, 2026 04:12

mountiny approved these changes Oct 23, 2026

View reviewed changes

mountiny merged commit dd8a925 into Expensify:main Oct 23, 2026
36 of 38 checks passed

OSBotify mentioned this pull request Oct 23, 2026

Deploy Checklist: New Expensify 2026-10-23 #104870

Open

Conversation

collectioneur commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation of Change

Fixed Issues

Tests

Offline tests

QA Steps

PR Author Checklist

Screenshots/Videos

Uh oh!

codecov Bot commented Oct 8, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

collectioneur commented Oct 16, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

chatgpt-codex-connector Bot commented Oct 16, 2026

Uh oh!

melvin-bot Bot commented Oct 16, 2026

Uh oh!

mikolajpochec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JmillsExpensify left a comment

Choose a reason for hiding this comment

Uh oh!

collectioneur commented Oct 19, 2026

Uh oh!

This comment was marked as resolved.

MelvinBot commented Oct 21, 2026

Uh oh!

QichenZhu commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer Checklist

Screenshots/Videos

Uh oh!

QichenZhu commented Oct 21, 2026

Uh oh!

QichenZhu commented Oct 21, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

QichenZhu commented Oct 22, 2026

Uh oh!

collectioneur commented Oct 22, 2026

Uh oh!

QichenZhu left a comment

Choose a reason for hiding this comment

Uh oh!

mountiny left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026

Uh oh!

OSBotify commented Oct 23, 2026

Uh oh!

OSBotify commented Oct 23, 2026

Uh oh!

MelvinBot commented Oct 23, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

collectioneur commented Oct 8, 2026 •

edited

Loading

codecov Bot commented Oct 8, 2026 •

edited by github-actions Bot

Loading

chatgpt-codex-connector Bot commented Oct 16, 2026 •

edited

Loading

QichenZhu commented Oct 21, 2026 •

edited

Loading