Throw assertion error when a Hero has a Hero child. (#28470)

packages/flutter/lib/src/widgets/heroes.dart

@@ -126,6 +126,7 @@ class Hero extends StatefulWidget {
   /// Create a hero.
   ///
   /// The [tag] and [child] parameters must not be null.
+  /// The [child] parameter and all of the its descendants must not be [Hero]s.
   const Hero({
     Key key,
     @required this.tag,
@@ -295,6 +296,11 @@ class _HeroState extends State<Hero> {
 
   @override
   Widget build(BuildContext context) {
+    assert(
+      context.ancestorWidgetOfExactType(Hero) == null,
+      'A Hero widget cannot be the descendant of another Hero widget.'
+    );
+
     if (_placeholderSize != null) {
       if (widget.placeholderBuilder == null) {
         return SizedBox(

packages/flutter/test/widgets/heroes_test.dart

@@ -1610,4 +1610,88 @@ void main() {
     expect(find.byKey(smallContainer), isInCard);
     expect(tester.getSize(find.byKey(smallContainer)), const Size(100,100));
   });
+
+  testWidgets('Hero within a Hero, throws', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Material(
+          child: Hero(
+            tag: 'a',
+            child: Hero(
+              tag: 'b',
+              child: Text('Child of a Hero'),
+            ),
+          ),
+        ),
+      ),
+    );
+
+    expect(tester.takeException(), isAssertionError);
+  });
+
+  testWidgets('Hero within a Hero subtree, throws', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Material(
+          child: Container(
+            child: const Hero(
+              tag: 'a',
+              child: Hero(
+                tag: 'b',
+                child: Text('Child of a Hero'),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+
+    expect(tester.takeException(), isAssertionError);
+  });
+
+  testWidgets('Hero within a Hero subtree with Builder, throws', (
+      WidgetTester tester) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Material(
+          child: Hero(
+            tag: 'a',
+            child: Builder(
+              builder: (BuildContext context) {
+                return const Hero(
+                  tag: 'b',
+                  child: Text('Child of a Hero'),
+                );
+              },
+            ),
+          ),
+        ),
+      ),
+    );
+
+    expect(tester.takeException(),isAssertionError);
+  });
+
+  testWidgets('Hero within a Hero subtree with LayoutBuilder, throws', (
+      WidgetTester tester) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Material(
+          child: Hero(
+            tag: 'a',
+            child: LayoutBuilder(
+              builder: (BuildContext context, BoxConstraints constraints) {
+                return const Hero(
+                  tag: 'b',
+                  child: Text('Child of a Hero'),
+                );
+              },
+            ),
+          ),
+        ),
+      ),
+    );
+
+    expect(tester.takeException(), isAssertionError);
+  });
 }