Add Material 3 Popup Menu example and update existing example (#114228)

examples/api/lib/material/popup_menu/popup_menu.0.dart

@@ -0,0 +1,66 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/// Flutter code sample for [PopupMenuButton].
+
+import 'package:flutter/material.dart';
+
+// This is the type used by the popup menu below.
+enum SampleItem { itemOne, itemTwo, itemThree }
+
+void main() => runApp(const PopupMenuApp());
+
+class PopupMenuApp extends StatelessWidget {
+  const PopupMenuApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return const MaterialApp(
+      home: PopupMenuExample(),
+    );
+  }
+}
+
+class PopupMenuExample extends StatefulWidget {
+  const PopupMenuExample({super.key});
+
+  @override
+  State<PopupMenuExample> createState() => _PopupMenuExampleState();
+}
+
+class _PopupMenuExampleState extends State<PopupMenuExample> {
+  SampleItem? selectedMenu;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('PopupMenuButton')),
+      body: Center(
+        child: PopupMenuButton<SampleItem>(
+          initialValue: selectedMenu,
+          // Callback that sets the selected popup menu item.
+          onSelected: (SampleItem item) {
+            setState(() {
+              selectedMenu = item;
+            });
+          },
+          itemBuilder: (BuildContext context) => <PopupMenuEntry<SampleItem>>[
+            const PopupMenuItem<SampleItem>(
+              value: SampleItem.itemOne,
+              child: Text('Item 1'),
+            ),
+            const PopupMenuItem<SampleItem>(
+              value: SampleItem.itemTwo,
+              child: Text('Item 2'),
+            ),
+            const PopupMenuItem<SampleItem>(
+              value: SampleItem.itemThree,
+              child: Text('Item 3'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}

examples/api/lib/material/popup_menu/popup_menu.1.dart

@@ -0,0 +1,67 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/// Flutter code sample for [PopupMenuButton].
+
+import 'package:flutter/material.dart';
+
+// This is the type used by the popup menu below.
+enum SampleItem { itemOne, itemTwo, itemThree }
+
+void main() => runApp(const PopupMenuApp());
+
+class PopupMenuApp extends StatelessWidget {
+  const PopupMenuApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      theme: ThemeData(useMaterial3: true, colorSchemeSeed: const Color(0xff6750a4)),
+      home: const PopupMenuExample(),
+    );
+  }
+}
+
+class PopupMenuExample extends StatefulWidget {
+  const PopupMenuExample({super.key});
+
+  @override
+  State<PopupMenuExample> createState() => _PopupMenuExampleState();
+}
+
+class _PopupMenuExampleState extends State<PopupMenuExample> {
+  SampleItem? selectedMenu;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('PopupMenuButton')),
+      body: Center(
+        child: PopupMenuButton<SampleItem>(
+          initialValue: selectedMenu,
+          // Callback that sets the selected popup menu item.
+          onSelected: (SampleItem item) {
+            setState(() {
+              selectedMenu = item;
+            });
+          },
+          itemBuilder: (BuildContext context) => <PopupMenuEntry<SampleItem>>[
+            const PopupMenuItem<SampleItem>(
+              value: SampleItem.itemOne,
+              child: Text('Item 1'),
+            ),
+            const PopupMenuItem<SampleItem>(
+              value: SampleItem.itemTwo,
+              child: Text('Item 2'),
+            ),
+            const PopupMenuItem<SampleItem>(
+              value: SampleItem.itemThree,
+              child: Text('Item 3'),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}

examples/api/lib/material/popupmenu/popupmenu.0.dart

@@ -1,77 +0,0 @@
-// Copyright 2014 The Flutter Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-
-/// Flutter code sample for [PopupMenuButton].
-
-import 'package:flutter/material.dart';
-
-// This is the type used by the popup menu below.
-enum Menu { itemOne, itemTwo, itemThree, itemFour }
-
-void main() => runApp(const MyApp());
-
-class MyApp extends StatelessWidget {
-  const MyApp({super.key});
-
-  static const String _title = 'Flutter Code Sample';
-
-  @override
-  Widget build(BuildContext context) {
-    return const MaterialApp(
-      debugShowCheckedModeBanner: false,
-      title: _title,
-      home: MyStatefulWidget(),
-    );
-  }
-}
-
-class MyStatefulWidget extends StatefulWidget {
-  const MyStatefulWidget({super.key});
-
-  @override
-  State<MyStatefulWidget> createState() => _MyStatefulWidgetState();
-}
-
-class _MyStatefulWidgetState extends State<MyStatefulWidget> {
-  String _selectedMenu = '';
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      appBar: AppBar(
-        actions: <Widget>[
-          // This button presents popup menu items.
-          PopupMenuButton<Menu>(
-          // Callback that sets the selected popup menu item.
-          onSelected: (Menu item) {
-            setState(() {
-              _selectedMenu = item.name;
-            });
-          },
-          itemBuilder: (BuildContext context) => <PopupMenuEntry<Menu>>[
-            const PopupMenuItem<Menu>(
-              value: Menu.itemOne,
-              child: Text('Item 1'),
-            ),
-            const PopupMenuItem<Menu>(
-              value: Menu.itemTwo,
-              child: Text('Item 2'),
-            ),
-            const PopupMenuItem<Menu>(
-              value: Menu.itemThree,
-              child: Text('Item 3'),
-            ),
-            const PopupMenuItem<Menu>(
-              value: Menu.itemFour,
-              child: Text('Item 4'),
-            ),
-          ]),
-        ],
-      ),
-      body: Center(
-        child: Text('_selectedMenu: $_selectedMenu'),
-      ),
-    );
-  }
-}

examples/api/test/material/popup_menu/popup_menu.0_test.dart

@@ -0,0 +1,33 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/popup_menu/popup_menu.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Can open popup menu', (WidgetTester tester) async {
+    const String menuItem = 'Item 1';
+
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: example.PopupMenuApp(),
+        ),
+      ),
+    );
+
+    expect(find.text(menuItem), findsNothing);
+
+    // Open popup menu.
+    await tester.tap(find.byIcon(Icons.adaptive.more));
+    await tester.pumpAndSettle();
+    expect(find.text(menuItem), findsOneWidget);
+
+    // Close popup menu.
+    await tester.tapAt(const Offset(1, 1));
+    await tester.pumpAndSettle();
+    expect(find.text(menuItem), findsNothing);
+  });
+}

examples/api/test/material/popup_menu/popup_menu.1_test.dart

@@ -0,0 +1,33 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/popup_menu/popup_menu.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Can open popup menu', (WidgetTester tester) async {
+    const String menuItem = 'Item 1';
+
+    await tester.pumpWidget(
+      const MaterialApp(
+        home: Scaffold(
+          body: example.PopupMenuApp(),
+        ),
+      ),
+    );
+
+    expect(find.text(menuItem), findsNothing);
+
+    // Open popup menu.
+    await tester.tap(find.byIcon(Icons.adaptive.more));
+    await tester.pumpAndSettle();
+    expect(find.text(menuItem), findsOneWidget);
+
+    // Close popup menu.
+    await tester.tapAt(const Offset(1, 1));
+    await tester.pumpAndSettle();
+    expect(find.text(menuItem), findsNothing);
+  });
+}

examples/api/test/material/popupmenu/popupmenu.0_test.dart

@@ -1,34 +0,0 @@
-// Copyright 2014 The Flutter Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-
-import 'package:flutter/material.dart';
-import 'package:flutter_api_samples/material/popupmenu/popupmenu.0.dart' as example;
-import 'package:flutter_test/flutter_test.dart';
-
-void main() {
-  testWidgets('Can select a menu item', (WidgetTester tester) async {
-    final Key popupButtonKey = UniqueKey();
-    await tester.pumpWidget(
-      MaterialApp(
-        home: Scaffold(
-          body: example.MyStatefulWidget(
-            key: popupButtonKey,
-          ),
-        ),
-      ),
-    );
-
-    await tester.tap(find.byKey(popupButtonKey));
-    await tester.pump();
-    await tester.pump(const Duration(seconds: 1)); // finish the menu animation
-    await tester.tapAt(const Offset(1.0, 1.0));
-    await tester.pumpAndSettle();
-    expect(find.text('_selectedMenu: itemOne'), findsNothing);
-  });
-
-  testWidgets('Does not show debug banner', (WidgetTester tester) async {
-    await tester.pumpWidget(const example.MyApp());
-    expect(find.byType(CheckedModeBanner), findsNothing);
-  });
-}

packages/flutter/lib/src/material/popup_menu.dart

@@ -1017,10 +1017,17 @@ typedef PopupMenuItemBuilder<T> = List<PopupMenuEntry<T>> Function(BuildContext
 /// platform).
 ///
 /// {@tool dartpad}
-/// This example shows a menu with four items, selecting between an enum's
+/// This example shows a menu with three items, selecting between an enum's
-/// values and setting a `_selectedMenu` field based on the selection
+/// values and setting a `selectedMenu` field based on the selection.
 ///
-/// ** See code in examples/api/lib/material/popupmenu/popupmenu.0.dart **
+/// ** See code in examples/api/lib/material/popup_menu/popup_menu.0.dart **
+/// {@end-tool}
+///
+/// {@tool dartpad}
+/// This sample shows the creation of a popup menu, as described in:
+/// https://m3.material.io/components/menus/overview
+///
+/// ** See code in examples/api/lib/material/popup_menu/popup_menu.1.dart **
 /// {@end-tool}
 ///
 /// See also: