Add Material 3 Popup Menu example and update existing example (flutte…

…r#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/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);
+  });
+}

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
-/// values and setting a `_selectedMenu` field based on the selection
+/// This example shows a menu with three items, selecting between an enum's
+/// 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: