From 14f2f98f9de6fa75abf67bc04bc62ed91b95ebc0 Mon Sep 17 00:00:00 2001
From: Shi-Hao Hong <shihaohong@google.com>
Date: Fri, 26 Apr 2019 07:55:29 -0700
Subject: [PATCH] Add InkWell docs on transitions and ink splash clipping
 (#31316)

---
 .../flutter/lib/src/material/ink_well.dart    | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/packages/flutter/lib/src/material/ink_well.dart b/packages/flutter/lib/src/material/ink_well.dart
index 8bd5ed2188..37c4e079c3 100644
--- a/packages/flutter/lib/src/material/ink_well.dart
+++ b/packages/flutter/lib/src/material/ink_well.dart
@@ -616,6 +616,49 @@ class _InkResponseState<T extends InkResponse> extends State<T> with AutomaticKe
 /// ancestor to the ink well). The [MaterialType.transparency] material
 /// kind can be used for this purpose.
 ///
+/// ### The ink splashes don't track the size of an animated container
+/// If the size of an InkWell's [Material] ancestor changes while the InkWell's
+/// splashes are expanding, you may notice that the splashes aren't clipped
+/// correctly. This can't be avoided.
+///
+/// An example of this situation is as follows:
+///
+/// {@tool snippet --template=stateful_widget_scaffold}
+///
+/// Tap the container to cause it to grow. Then, tap it again and hold before
+/// the widget reaches its maximum size to observe the clipped ink splash.
+///
+/// ```dart
+/// double sideLength = 50;
+///
+/// Widget build(BuildContext context) {
+///   return Center(
+///     child: AnimatedContainer(
+///       height: sideLength,
+///       width: sideLength,
+///       duration: Duration(seconds: 2),
+///       curve: Curves.easeIn,
+///       child: Material(
+///         color: Colors.yellow,
+///         child: InkWell(
+///           onTap: () {
+///             setState(() {
+///               sideLength == 50 ? sideLength = 100 : sideLength = 50;
+///             });
+///           },
+///         ),
+///       ),
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
+/// An InkWell's splashes will not properly update to conform to changes if the
+/// size of its underlying [Material], where the splashes are rendered, changes
+/// during animation. You should avoid using InkWells within [Material] widgets
+/// that are changing size.
+///
 /// See also:
 ///
 ///  * [GestureDetector], for listening for gestures without ink splashes.