Migration guide for moving from BottomNavigationBar to NavigationBar (#128263)

Fixes https://github.com/flutter/flutter/issues/127213

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

@@ -36,20 +36,22 @@ class _NavigationExampleState extends State<NavigationExample> {
             currentPageIndex = index;
           });
         },
+        indicatorColor: Colors.amber[800],
         selectedIndex: currentPageIndex,
         destinations: const <Widget>[
           NavigationDestination(
-            icon: Icon(Icons.explore),
+            selectedIcon: Icon(Icons.home),
-            label: 'Explore',
+            icon: Icon(Icons.home_outlined),
+            label: 'Home',
           ),
           NavigationDestination(
-            icon: Icon(Icons.commute),
+            icon: Icon(Icons.business),
-            label: 'Commute',
+            label: 'Business',
           ),
           NavigationDestination(
-            selectedIcon: Icon(Icons.bookmark),
+            selectedIcon: Icon(Icons.school),
-            icon: Icon(Icons.bookmark_border),
+            icon: Icon(Icons.school_outlined),
-            label: 'Saved',
+            label: 'School',
           ),
         ],
       ),

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

@@ -16,20 +16,20 @@ void main() {
     final NavigationBar navigationBarWidget = tester.firstWidget(find.byType(NavigationBar));
 
     /// NavigationDestinations must be rendered
-    expect(find.text('Explore'), findsOneWidget);
+    expect(find.text('Home'), findsOneWidget);
-    expect(find.text('Commute'), findsOneWidget);
+    expect(find.text('Business'), findsOneWidget);
-    expect(find.text('Saved'), findsOneWidget);
+    expect(find.text('School'), findsOneWidget);
 
     /// initial index must be zero
     expect(navigationBarWidget.selectedIndex, 0);
 
     /// switch to second tab
-    await tester.tap(find.text('Commute'));
+    await tester.tap(find.text('Business'));
     await tester.pumpAndSettle();
     expect(find.text('Page 2'), findsOneWidget);
 
     /// switch to third tab
-    await tester.tap(find.text('Saved'));
+    await tester.tap(find.text('School'));
     await tester.pumpAndSettle();
     expect(find.text('Page 3'), findsOneWidget);
   });

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

@@ -100,15 +100,36 @@ enum BottomNavigationBarLandscapeLayout {
 ///
 /// ## Updating to [NavigationBar]
 ///
-/// There is an updated version of this component, [NavigationBar],
+/// The [NavigationBar] widget's visuals
-/// that's preferred for new applications and applications that are
+/// are a little bit different, see the Material 3 spec at
-/// configured for Material 3 (see [ThemeData.useMaterial3]). The
-/// [NavigationBar] widget's visuals are a little bit different, see
-/// the Material 3 spec at
 /// <https://m3.material.io/components/navigation-bar/overview> for
-/// more details. The API is similar, destinations are defined with
+/// more details.
-/// [NavigationDestination]s and [NavigationBar.onDestinationSelected]
+///
-/// is called when a destination is tapped.
+/// The [NavigationBar] widget's API is also slightly different.
+/// To update from [BottomNavigationBar] to [NavigationBar], you will
+/// need to make the following changes.
+///
+/// 1. Instead of using [BottomNavigationBar.items], which
+/// takes a list of [BottomNavigationBarItem]s, use
+/// [NavigationBar.destinations], which takes a list of widgets.
+/// Usually, you use a list of [NavigationDestination] widgets.
+/// Just like [BottomNavigationBarItem]s, [NavigationDestination]s
+/// have a label and icon field.
+///
+/// 2. Instead of using [BottomNavigationBar.onTap],
+/// use [NavigationBar.onDestinationSelected], which is also
+/// a callback that is called when the user taps on a
+/// navigation bar item.
+///
+/// 3. Instead of using [BottomNavigationBar.currentIndex],
+/// use [NavigationBar.selectedIndex], which is also an integer
+/// that represents the index of the selected destination.
+///
+/// 4. You may also need to make changes to the styling of the
+/// [NavigationBar], see the properties in the [NavigationBar]
+/// constructor for more details.
+///
+/// ## Using [BottomNavigationBar]
 ///
 /// {@tool dartpad}
 /// This example shows a [BottomNavigationBar] as it is used within a [Scaffold]
@@ -122,6 +143,13 @@ enum BottomNavigationBarLandscapeLayout {
 /// {@end-tool}
 ///
 /// {@tool dartpad}
+/// This example shows how you would migrate the above [BottomNavigationBar]
+/// to the new [NavigationBar].
+///
+/// ** See code in examples/api/lib/material/navigation_bar/navigation_bar.0.dart **
+/// {@end-tool}
+///
+/// {@tool dartpad}
 /// This example shows a [BottomNavigationBar] as it is used within a [Scaffold]
 /// widget. The [BottomNavigationBar] has four [BottomNavigationBarItem]
 /// widgets, which means it defaults to [BottomNavigationBarType.shifting], and