[docs] Add guide for transformations example#4289
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new documentation guide explaining how to implement a “photo viewer” interaction (pan + pinch + rotation simultaneously) using matrix composition, and updates the transformations examples to use 3×3 affine matrices instead of 4×4 matrices.
Changes:
- Added a new “Transforming a view” guide with conceptual explanation and a full example.
- Updated both example-app transformations screens to use 3×3 matrix helpers (
identity3/multiply3/translate3/scale3/rotate3) and adjusted translation indices accordingly. - Aligned transformed-coordinate conversion to the new 3×3 matrix layout (2×2 linear part extracted from
[0,1,3,4]).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| packages/docs-gesture-handler/docs/guides/transformations.mdx | New guide documenting multi-gesture transforms via affine matrices, including a full example snippet. |
| apps/common-app/src/new_api/complicated/transformations/index.tsx | Migrates the new API transformations example from 4×4 to 3×3 matrix math and updates transform extraction. |
| apps/common-app/src/legacy/v2_api/transformations/index.tsx | Migrates the legacy/v2 API transformations example from 4×4 to 3×3 matrix math and updates transform extraction. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Use a matrix, not separate transforms | ||
|
|
||
| The obvious approach — keeping separate `scale`, `rotation` and `translation` values and passing them to a `transform` array — falls apart once the gestures combine. The array applies its entries in a fixed order, so you can't decide whether scaling happens before or after rotation, and there's nowhere to accumulate the result of one gesture so the next can build on it. |
There was a problem hiding this comment.
I don't have much experience writing docs, but wouldn't it be better if the user first sees how it should be done, and later, if they are curious, they can read about other approaches and their disadvantages?
|
|
||
| ## Use a matrix, not separate transforms | ||
|
|
||
| The obvious approach — keeping separate `scale`, `rotation` and `translation` values and passing them to a `transform` array — falls apart once the gestures combine. The array applies its entries in a fixed order, so you can't decide whether scaling happens before or after rotation, and there's nowhere to accumulate the result of one gesture so the next can build on it. |
There was a problem hiding this comment.
The array applies its entries in a fixed order, so you can't decide whether scaling happens before or after rotation
You can, and that's exactly why it's an array of objects and not a simple object with all the transform props.
The issue is that every little move/scale/rotation would need to be added to the array, and React would build a new matrix from those entries on each render.
Description
Originally we thought about adding
useTransformGesturehook. However, we decided to drop the idea and describe important caveats in docs guide.I've also updated transformations examples to use 3x3 matrices instead of 4x4.
Test plan