Create new page transition for M3 (#158881)

This PR is to add a new page transition for Material 3. 

The new builder matches the latest Android page transition behavior;
while the new page slides in from right to left, it fades in at the same
time and the old page slides out from right to left, fading out at the
same time. When both pages are fading in/out, the black background might
show up, so I added a `ColoredBox` for the slides-out page whose color
defaults to `ColorScheme.surface`. The `backgroundColor` property can be
used to customize the default transition color.

This demo shows the forward and backward behaviors.


https://github.com/user-attachments/assets/a806f25d-8564-4cad-8dfc-eb4585294181

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

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

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

@@ -15,7 +15,6 @@ class PageTransitionsThemeApp extends StatelessWidget {
   Widget build(BuildContext context) {
     return MaterialApp(
       theme: ThemeData(
-        useMaterial3: true,
         // Defines the page transition animations used by MaterialPageRoute
         // for different target platforms.
         // Non-specified target platforms will default to

examples/api/lib/material/page_transitions_theme/page_transitions_theme.3.dart

@@ -0,0 +1,149 @@
+// 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';
+
+/// Flutter code sample for the default Android U page transition theme
+/// [FadeForwardsPageTransitionsBuilder]. Tapping each list tile navigates to
+/// a second page, which slides in from right to left while fading in.
+/// Simultaneously, the first page slides out in the same direction while
+/// fading out.
+
+void main() => runApp(const PageTransitionsThemeApp());
+
+class PageTransitionsThemeApp extends StatelessWidget {
+  const PageTransitionsThemeApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      debugShowCheckedModeBanner: false,
+      theme: ThemeData(
+        pageTransitionsTheme: PageTransitionsTheme(
+          builders: Map<TargetPlatform, PageTransitionsBuilder>.fromIterable(
+            TargetPlatform.values, value: (_) => const FadeForwardsPageTransitionsBuilder()
+          ),
+        ),
+      ),
+      home: const HomePage(),
+    );
+  }
+}
+
+class HomePage extends StatelessWidget {
+  const HomePage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        leading: IconButton(icon: const Icon(Icons.dehaze), onPressed: () {}),
+        actions: <Widget>[
+          IconButton(icon: const Icon(Icons.search), onPressed: () {}),
+          IconButton(icon: const Icon(Icons.more_vert), onPressed: () {}),
+        ],
+      ),
+      body: Column(
+        children: <Widget>[
+          Text('Messages', style: Theme.of(context).textTheme.headlineLarge),
+          Expanded(
+            child: Padding(
+              padding: const EdgeInsets.all(20.0),
+              child: Card(
+                clipBehavior: Clip.antiAlias,
+                elevation: 0,
+                color: Theme.of(context).colorScheme.surfaceContainerLowest,
+                child: ListView(
+                  children: List<Widget>.generate(Colors.primaries.length, (int index) {
+                    final Text kittenName = Text('Kitten $index');
+                    final CircleAvatar avatar = CircleAvatar(backgroundColor: Colors.primaries[index]);
+                    final String message = index.isEven
+                        ? 'Hello hooman! My name is Kitten $index'
+                        : "What's up hooman! My name is Kitten $index";
+                    return ListTile(
+                      leading: avatar,
+                      title: kittenName,
+                      subtitle: Text(message),
+                      trailing: Text('$index seconds ago'),
+                      onTap: () {
+                        Navigator.of(context).push(
+                          MaterialPageRoute<SecondPage>(
+                            builder: (BuildContext context)
+                              => SecondPage(
+                                kittenName: kittenName,
+                                avatar: avatar,
+                                message: message,
+                              ),
+                          ),
+                        );
+                      },
+                    );
+                  }),
+                ),
+              ),
+            ),
+          ),
+        ],
+      )
+    );
+  }
+}
+
+class SecondPage extends StatelessWidget {
+  const SecondPage({
+    super.key,
+    required this.kittenName,
+    required this.avatar,
+    required this.message,
+  });
+  final Text kittenName;
+  final CircleAvatar avatar;
+  final String message;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        leading: const BackButton(),
+        title: kittenName,
+        centerTitle: false,
+        actions: <Widget>[
+          IconButton(icon: const Icon(Icons.search), onPressed: () {}),
+          IconButton(icon: const Icon(Icons.more_vert), onPressed: () {}),
+        ],
+      ),
+      body: Padding(
+        padding: const EdgeInsets.all(20.0),
+        child: IntrinsicHeight(
+          child: Row(
+            children: <Widget>[
+              avatar,
+              ConstrainedBox(
+                constraints: const BoxConstraints(minHeight: 50),
+                child: Card(
+                  elevation: 0.0,
+                  shape: const RoundedRectangleBorder(
+                    borderRadius: BorderRadius.only(
+                      topLeft: Radius.circular(20),
+                      topRight: Radius.circular(20),
+                      bottomLeft: Radius.circular(5),
+                      bottomRight: Radius.circular(20),
+                    )
+                  ),
+                  color: Theme.of(context).colorScheme.surfaceContainerLowest,
+                  child: Center(
+                    child: Padding(
+                      padding: const EdgeInsets.symmetric(horizontal: 15.0),
+                      child: Text(message)
+                    ),
+                  ),
+                ),
+              )
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}

examples/api/lib/widgets/heroes/hero.1.dart

@@ -18,9 +18,8 @@ class HeroApp extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return MaterialApp(
-      theme: ThemeData(useMaterial3: true),
-      home: const HeroExample(),
+    return const MaterialApp(
+      home: HeroExample(),
     );
   }
 }

examples/api/test/material/page_transitions_theme/page_transitions_theme.3_test.dart

@@ -0,0 +1,30 @@
+// 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/page_transitions_theme/page_transitions_theme.3.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Page transition', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.PageTransitionsThemeApp(),
+    );
+
+    final Finder homePage = find.byType(example.HomePage);
+    expect(homePage, findsOneWidget);
+
+    final Finder kitten0 = find.widgetWithText(ListTile, 'Kitten 0');
+    expect(kitten0, findsOneWidget);
+
+    await tester.tap(kitten0);
+    await tester.pumpAndSettle();
+    expect(find.widgetWithText(AppBar, 'Kitten 0'), findsOneWidget);
+
+    await tester.tap(find.byType(BackButton));
+    await tester.pumpAndSettle();
+
+    expect(find.widgetWithText(ListTile, 'Kitten 0'), findsOneWidget);
+  });
+}