[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?
There was a problem hiding this comment.
The opening paragraph has link to the example. There's also "Full example" section and I think it would look strange if we put it earlier.
if they are curious, they can read about other approaches and their disadvantages?
My point when creating this guide was to explain how to do it correctly (and why other approach is bad) and then show example, not the other way around. Of course we can change it, but I think this approach fits better.
There was a problem hiding this comment.
My point when creating this guide was to explain how to do it correctly (and why other approach is bad) and then show example, not the other way around.
It is the other way around - it starts with why the other approach is bad, then explains how to do it correctly.
There was a problem hiding this comment.
It is the other way around - it starts with why the other approach is bad, then explains how to do it correctly.
Okay, I think we are focused on 2 different things 😅 That's why I used word "and". By the "other way around" I meant first showing the example.
Anyway, I think I know what you mean by that. I'll rephrase it and get back to you.
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