Skip to content

Conversation

@Rushikeshbhavsar20
Copy link
Contributor

@Rushikeshbhavsar20 Rushikeshbhavsar20 commented Aug 22, 2025

Description 📝

This PR updates the documentation for the transformHitTests parameter in the Transform widget to resolve ambiguity in the API documentation that has caused hit testing issues for developers.

The current documentation simply states "Whether to apply the transformation when performing hit tests" which is ambiguous. As seen in issues like #27587, developers expect transformed widgets to receive touch events across their entire visual area, but hits only register within the parent's original bounds.

The core issue: The documentation lacks clarity on:
❌ Hit test coordinate system transformation vs. hit test bounds expansion
🔄 Parent widget bounds as the constraint for hit test registration
⚠️ The distinction between visual rendering bounds and interactive bounds

Before (Current Documentation)

Current documentation is vague: "Whether to apply the transformation when performing hit tests"

Screenshot 2025-08-22 214745

After (Improved Documentation)

Screenshot 2025-08-22 214808

New documentation clearly explains behavior, limitations, and solutions

Changes made:

  • 🔧 Clarified that transformHitTests transforms registered hits into the child's resulting coordinate system
  • 🚨 Explicitly documented the critical limitation: only hits within parent bounds can be registered
  • 📚 Explained the behavior difference between true and false settings with concrete examples of transformation types
  • 💡 Added guidance for common workarounds: expanding parent bounds or using Overlay for out-of-bounds elements

Issues Fixed 🐛

Fixes #78120

Related issues that motivated this change: 🔗

Note: This PR is test-exempt as it only updates documentation comments without changing any functionality.

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

Fixes flutter#78120

- Clarified that only hits within parent bounds can be registered
- Explained coordinate transformation behavior for both true/false cases
- Added guidance for handling out-of-bounds interactive elements
- Referenced Overlay as alternative solution
@flutter-dashboard
Copy link

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.

@github-actions github-actions bot added the framework flutter/packages/flutter repository. See also f: labels. label Aug 22, 2025
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request significantly improves the documentation for the transformHitTests property on the Transform widget. The new documentation is much clearer and addresses a common point of confusion for developers by explicitly stating the limitations of hit testing with transforms. The other changes in this PR are minor formatting adjustments. My review includes a suggestion to further enhance the documentation by adding a code example, as recommended by the style guide.

- Removed outdated explanation of hit test behavior.
- Added detailed description of coordinate transformation rules.
- Included runnable code snippet demonstrating scaling and tap region limits.

Fixes flutter#78120
Copy link
Contributor

@justinmc justinmc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for improving Flutter's docs! This is a tricky topic.

Comment on lines 1790 to 1792
/// **Important:** Only hits within the parent's original bounds can be registered
/// and transformed. Any part of the child extending outside the parent's bounds
/// will not receive touch events.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for including this, I think it's tricky. See #75747.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the reference! I went through it and made some changes to the Important note. Please review when you get a chance.

Copy link
Contributor

@victorsanni victorsanni left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Thanks for the PR.

Copy link
Member

@loic-sharma loic-sharma left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the wonderful doc!

@loic-sharma loic-sharma added the autosubmit Merge PR when tree becomes green via auto submit App label Sep 12, 2025
@auto-submit auto-submit bot added this pull request to the merge queue Sep 12, 2025
Merged via the queue into flutter:master with commit 6e66c14 Sep 12, 2025
79 checks passed
@flutter-dashboard flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Sep 12, 2025
@Rushikeshbhavsar20 Rushikeshbhavsar20 deleted the fix-78120 branch September 13, 2025 10:12
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 13, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 13, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 14, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 14, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 14, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 15, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 15, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 15, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Sep 15, 2025
auto-submit bot pushed a commit to flutter/packages that referenced this pull request Sep 15, 2025
flutter/flutter@f331a55...29a238d

2025-09-15 [email protected] Roll Skia from d84a369255c4 to f950263bb3d4 (1 revision) (flutter/flutter#175354)
2025-09-15 [email protected] Roll Fuchsia Linux SDK from 4ZIBcdI2x_y8trVYz... to wzk_HjPLGu-mlg5hC... (flutter/flutter#175349)
2025-09-15 [email protected] Roll Dart SDK from 24179911b2fe to 50e61e5bff51 (2 revisions) (flutter/flutter#175346)
2025-09-15 [email protected] Roll Skia from 785f8859c7b9 to d84a369255c4 (5 revisions) (flutter/flutter#175342)
2025-09-15 [email protected] Roll Dart SDK from 628b3f869d9b to 24179911b2fe (1 revision) (flutter/flutter#175331)
2025-09-15 [email protected] Roll Skia from 4fb7e988c981 to 785f8859c7b9 (1 revision) (flutter/flutter#175330)
2025-09-14 [email protected] Roll Skia from 64c5ab69997f to 4fb7e988c981 (1 revision) (flutter/flutter#175322)
2025-09-14 [email protected] Roll Fuchsia Linux SDK from TrB_3av7CK7a5Wb0h... to 4ZIBcdI2x_y8trVYz... (flutter/flutter#175319)
2025-09-14 [email protected] Roll Skia from 7b489cee9eca to 64c5ab69997f (1 revision) (flutter/flutter#175316)
2025-09-13 [email protected] Roll Dart SDK from 5deba9e4e108 to 628b3f869d9b (1 revision) (flutter/flutter#175314)
2025-09-13 [email protected] Roll Fuchsia Linux SDK from b1AYfAFOnvBMHSsYL... to TrB_3av7CK7a5Wb0h... (flutter/flutter#175306)
2025-09-13 [email protected] Roll Dart SDK from e82f3fc8b2d5 to 5deba9e4e108 (1 revision) (flutter/flutter#175302)
2025-09-13 [email protected] Roll Skia from 3321829b90dd to 7b489cee9eca (1 revision) (flutter/flutter#175298)
2025-09-13 [email protected] [ios]Do not re-adds delaying recognizer on iOS 26 (flutter/flutter#175097)
2025-09-13 [email protected] Roll Skia from b2cdcf07b2b5 to 3321829b90dd (22 revisions) (flutter/flutter#175295)
2025-09-13 [email protected] Roll Dart SDK from 11dedad2d062 to e82f3fc8b2d5 (3 revisions) (flutter/flutter#175294)
2025-09-12 [email protected] Add semanticIndexOffset argument to SliverList.builder, SliverGrid.builder, and SliverFixedExtentList.builder (flutter/flutter#174856)
2025-09-12 [email protected] Fix crash when attaching to a device with multiple active flutter apps (flutter/flutter#175147)
2025-09-12 [email protected] Update transformHitTests documentation for clarity (flutter/flutter#174286)
2025-09-12 [email protected] Roll Skia from ead9277819fc to b2cdcf07b2b5 (1 revision) (flutter/flutter#175226)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
dixita0607 pushed a commit to dixita0607/flutter that referenced this pull request Sep 17, 2025
## Description 📝

This PR updates the documentation for the transformHitTests parameter in
the Transform widget to resolve ambiguity in the API documentation that
has caused hit testing issues for developers.

The current documentation simply states "Whether to apply the
transformation when performing hit tests" which is ambiguous. As seen in
issues like flutter#27587, developers expect transformed widgets to receive
touch events across their entire visual area, but hits only register
within the parent's original bounds.

**The core issue**:  The documentation lacks clarity on:
❌ Hit test coordinate system transformation vs. hit test bounds
expansion
🔄 Parent widget bounds as the constraint for hit test registration
⚠️ The distinction between visual rendering bounds and interactive
bounds

### Before (Current Documentation) 

*Current documentation is vague: "Whether to apply the transformation
when performing hit tests"*

<img width="1887" height="483" alt="Screenshot 2025-08-22 214745"
src="https://github.com/user-attachments/assets/24569be5-8dbe-4a02-8851-1546b8ac109e"
/>

### After (Improved Documentation) 
<img width="1091" height="293" alt="Screenshot 2025-08-22 214808"
src="https://github.com/user-attachments/assets/f8504134-eba7-43ea-a71f-d9a8740ff295"
/>

*New documentation clearly explains behavior, limitations, and
solutions*

**Changes made:** ✅
- 🔧 Clarified that `transformHitTests` transforms registered hits into
the child's resulting coordinate system
- 🚨 Explicitly documented the critical limitation: only hits within
parent bounds can be registered
- 📚 Explained the behavior difference between `true` and `false`
settings with concrete examples of transformation types
- 💡 Added guidance for common workarounds: expanding parent bounds or
using Overlay for out-of-bounds elements

## Issues Fixed 🐛

Fixes flutter#78120

**Related issues that motivated this change:** 🔗
- flutter#27587 - Developers confused why GestureDetector doesn't respond after
Transform
- Multiple developers reported spending significant time debugging this
behavior
- Common misconception that visual transformation expands the hit test
area

**Note**: This PR is test-exempt as it only updates documentation
comments without changing any functionality.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
mboetger pushed a commit to mboetger/flutter that referenced this pull request Sep 18, 2025
## Description 📝

This PR updates the documentation for the transformHitTests parameter in
the Transform widget to resolve ambiguity in the API documentation that
has caused hit testing issues for developers.

The current documentation simply states "Whether to apply the
transformation when performing hit tests" which is ambiguous. As seen in
issues like flutter#27587, developers expect transformed widgets to receive
touch events across their entire visual area, but hits only register
within the parent's original bounds.

**The core issue**:  The documentation lacks clarity on:
❌ Hit test coordinate system transformation vs. hit test bounds
expansion
🔄 Parent widget bounds as the constraint for hit test registration
⚠️ The distinction between visual rendering bounds and interactive
bounds

### Before (Current Documentation) 

*Current documentation is vague: "Whether to apply the transformation
when performing hit tests"*

<img width="1887" height="483" alt="Screenshot 2025-08-22 214745"
src="https://github.com/user-attachments/assets/24569be5-8dbe-4a02-8851-1546b8ac109e"
/>

### After (Improved Documentation) 
<img width="1091" height="293" alt="Screenshot 2025-08-22 214808"
src="https://github.com/user-attachments/assets/f8504134-eba7-43ea-a71f-d9a8740ff295"
/>

*New documentation clearly explains behavior, limitations, and
solutions*

**Changes made:** ✅
- 🔧 Clarified that `transformHitTests` transforms registered hits into
the child's resulting coordinate system
- 🚨 Explicitly documented the critical limitation: only hits within
parent bounds can be registered
- 📚 Explained the behavior difference between `true` and `false`
settings with concrete examples of transformation types
- 💡 Added guidance for common workarounds: expanding parent bounds or
using Overlay for out-of-bounds elements

## Issues Fixed 🐛

Fixes flutter#78120

**Related issues that motivated this change:** 🔗
- flutter#27587 - Developers confused why GestureDetector doesn't respond after
Transform
- Multiple developers reported spending significant time debugging this
behavior
- Common misconception that visual transformation expands the hit test
area

**Note**: This PR is test-exempt as it only updates documentation
comments without changing any functionality.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
Jaineel-Mamtora pushed a commit to Jaineel-Mamtora/flutter_forked that referenced this pull request Sep 24, 2025
## Description 📝

This PR updates the documentation for the transformHitTests parameter in
the Transform widget to resolve ambiguity in the API documentation that
has caused hit testing issues for developers.

The current documentation simply states "Whether to apply the
transformation when performing hit tests" which is ambiguous. As seen in
issues like flutter#27587, developers expect transformed widgets to receive
touch events across their entire visual area, but hits only register
within the parent's original bounds.

**The core issue**:  The documentation lacks clarity on:
❌ Hit test coordinate system transformation vs. hit test bounds
expansion
🔄 Parent widget bounds as the constraint for hit test registration
⚠️ The distinction between visual rendering bounds and interactive
bounds

### Before (Current Documentation) 

*Current documentation is vague: "Whether to apply the transformation
when performing hit tests"*

<img width="1887" height="483" alt="Screenshot 2025-08-22 214745"
src="https://github.com/user-attachments/assets/24569be5-8dbe-4a02-8851-1546b8ac109e"
/>

### After (Improved Documentation) 
<img width="1091" height="293" alt="Screenshot 2025-08-22 214808"
src="https://github.com/user-attachments/assets/f8504134-eba7-43ea-a71f-d9a8740ff295"
/>

*New documentation clearly explains behavior, limitations, and
solutions*

**Changes made:** ✅
- 🔧 Clarified that `transformHitTests` transforms registered hits into
the child's resulting coordinate system
- 🚨 Explicitly documented the critical limitation: only hits within
parent bounds can be registered
- 📚 Explained the behavior difference between `true` and `false`
settings with concrete examples of transformation types
- 💡 Added guidance for common workarounds: expanding parent bounds or
using Overlay for out-of-bounds elements

## Issues Fixed 🐛

Fixes flutter#78120

**Related issues that motivated this change:** 🔗
- flutter#27587 - Developers confused why GestureDetector doesn't respond after
Transform
- Multiple developers reported spending significant time debugging this
behavior
- Common misconception that visual transformation expands the hit test
area

**Note**: This PR is test-exempt as it only updates documentation
comments without changing any functionality.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 12, 2025
lucaantonelli pushed a commit to lucaantonelli/flutter that referenced this pull request Nov 21, 2025
## Description 📝

This PR updates the documentation for the transformHitTests parameter in
the Transform widget to resolve ambiguity in the API documentation that
has caused hit testing issues for developers.

The current documentation simply states "Whether to apply the
transformation when performing hit tests" which is ambiguous. As seen in
issues like flutter#27587, developers expect transformed widgets to receive
touch events across their entire visual area, but hits only register
within the parent's original bounds.

**The core issue**:  The documentation lacks clarity on:
❌ Hit test coordinate system transformation vs. hit test bounds
expansion
🔄 Parent widget bounds as the constraint for hit test registration
⚠️ The distinction between visual rendering bounds and interactive
bounds

### Before (Current Documentation) 

*Current documentation is vague: "Whether to apply the transformation
when performing hit tests"*

<img width="1887" height="483" alt="Screenshot 2025-08-22 214745"
src="https://github.com/user-attachments/assets/24569be5-8dbe-4a02-8851-1546b8ac109e"
/>

### After (Improved Documentation) 
<img width="1091" height="293" alt="Screenshot 2025-08-22 214808"
src="https://github.com/user-attachments/assets/f8504134-eba7-43ea-a71f-d9a8740ff295"
/>

*New documentation clearly explains behavior, limitations, and
solutions*

**Changes made:** ✅
- 🔧 Clarified that `transformHitTests` transforms registered hits into
the child's resulting coordinate system
- 🚨 Explicitly documented the critical limitation: only hits within
parent bounds can be registered
- 📚 Explained the behavior difference between `true` and `false`
settings with concrete examples of transformation types
- 💡 Added guidance for common workarounds: expanding parent bounds or
using Overlay for out-of-bounds elements

## Issues Fixed 🐛

Fixes flutter#78120

**Related issues that motivated this change:** 🔗
- flutter#27587 - Developers confused why GestureDetector doesn't respond after
Transform
- Multiple developers reported spending significant time debugging this
behavior
- Common misconception that visual transformation expands the hit test
area

**Note**: This PR is test-exempt as it only updates documentation
comments without changing any functionality.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Transforms transformHitTests description is not clear enough

4 participants