Add a custom shape example for AppBar.shape (#146421)

fixes [AppBar shape disappears on AppBar elevation change when scrolling](#145945)

### Description
This PR adds an example for complete custom app bar for the  `AppBar.shape` property.

### Preview

![Screenshot 2024-04-08 at 14 21 04](https://github.com/flutter/flutter/assets/48603081/ae3eda2b-b709-4652-9f2c-dd7b7dcfeb5c)

examples/api/lib/material/app_bar/app_bar.4.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 [AppBar.shape].
+
+void main() => runApp(const AppBarExampleApp());
+
+class AppBarExampleApp extends StatelessWidget {
+  const AppBarExampleApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return const MaterialApp(
+      home: AppBarExample(),
+    );
+  }
+}
+
+class AppBarExample extends StatelessWidget {
+  const AppBarExample({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final ColorScheme colorScheme = Theme.of(context).colorScheme;
+
+    return Scaffold(
+      appBar: AppBar(
+        shape: const CustomAppBarShape(),
+        backgroundColor: colorScheme.primaryContainer,
+        title: const Text('AppBar Sample'),
+        bottom: PreferredSize(
+          preferredSize: const Size.fromHeight(64.0),
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 16.0),
+            child: TextField(
+              decoration: InputDecoration(
+                border: OutlineInputBorder(
+                  borderSide: BorderSide(color: colorScheme.primary),
+                ),
+                enabledBorder: OutlineInputBorder(
+                  borderSide: BorderSide(color: colorScheme.onPrimaryContainer),
+                ),
+                filled: true,
+                hintText: 'Enter a search term',
+                fillColor: colorScheme.surface,
+                prefixIcon: Icon(
+                  Icons.search_rounded,
+                  color: colorScheme.primary
+                ),
+                suffixIcon: Icon(
+                  Icons.tune_rounded,
+                  color: colorScheme.primary
+                ),
+              )
+            ),
+          ),
+        ),
+      ),
+      body: ListView.builder(
+        padding: const EdgeInsets.only(top: 45.0),
+        itemCount: 20,
+        itemBuilder: (BuildContext context, int index) {
+          return ListTile(
+            title: Text('Item $index'),
+          );
+        },
+      ),
+    );
+  }
+}
+
+class CustomAppBarShape extends OutlinedBorder {
+  // Implementing the constructor allows the CustomAppBarShape to be
+  // properly compared when calling the `identical` method.
+  const CustomAppBarShape({ super.side });
+
+   Path _getPath(Rect rect) {
+    final Path path = Path();
+    final Size size = Size(rect.width, rect.height * 1.5) ;
+
+    final double p0 = size.height * 0.75;
+    path.lineTo(0.0, p0);
+
+    final Offset controlPoint = Offset(size.width * 0.4, size.height);
+    final Offset endPoint = Offset(size.width, size.height / 2);
+    path.quadraticBezierTo(controlPoint.dx, controlPoint.dy, endPoint.dx, endPoint.dy);
+
+    path.lineTo(size.width, 0.0);
+    path.close();
+
+    return path;
+   }
+
+  @override
+  Path getOuterPath(Rect rect, {TextDirection? textDirection}) {
+    return _getPath(rect.inflate(side.width));
+  }
+
+  @override
+  Path getInnerPath(Rect rect, {TextDirection? textDirection}) {
+    return _getPath(rect);
+  }
+
+  @override
+  void paint(Canvas canvas, Rect rect, {TextDirection? textDirection}) {
+    if (rect.isEmpty) {
+      return;
+    }
+    canvas.drawPath(
+      getOuterPath(rect, textDirection: textDirection),
+      side.toPaint(),
+    );
+  }
+
+  @override
+  ShapeBorder scale(double t) {
+    return CustomAppBarShape(side: side.scale(t));
+  }
+
+  @override
+  OutlinedBorder copyWith({BorderSide? side}) {
+    return CustomAppBarShape(side: side ?? this.side);
+  }
+
+  // The lerpFrom method is necessary for the CustomAppBarShape to be
+  // properly animated when changing the AppBar shape and when
+  // the AppBar is rebuilt.
+  @override
+  ShapeBorder? lerpFrom(ShapeBorder? a, double t) {
+    if (a is CustomAppBarShape) {
+      return CustomAppBarShape(side: BorderSide.lerp(a.side, side, t));
+    }
+    return super.lerpFrom(a, t);
+  }
+
+  // The lerpTo method is necessary for the CustomAppBarShape to be
+  // properly animated when changing the AppBar shape and when
+  // the AppBar is rebuilt.
+  @override
+  ShapeBorder? lerpTo(ShapeBorder? b, double t) {
+    if (b is CustomAppBarShape) {
+      return CustomAppBarShape(side: BorderSide.lerp(b.side, side, t));
+    }
+    return super.lerpTo(b, t);
+  }
+}

examples/api/test/material/app_bar/app_bar.4_test.dart

@@ -0,0 +1,34 @@
+// 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/app_bar/app_bar.4.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('AppBar uses custom shape', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.AppBarExampleApp(),
+    );
+
+    Material getMaterial() => tester.widget<Material>(find.descendant(
+      of: find.byType(AppBar),
+      matching: find.byType(Material),
+    ));
+    expect(getMaterial().shape, const example.CustomAppBarShape());
+  });
+
+  testWidgets('AppBar bottom contains TextField', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.AppBarExampleApp(),
+    );
+
+    final Finder textFieldFinder = find.descendant(
+      of: find.byType(AppBar),
+      matching: find.byType(TextField),
+    );
+
+    expect(textFieldFinder, findsOneWidget);
+  });
+}

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

@@ -479,6 +479,12 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
   /// zero.
   /// {@endtemplate}
   ///
+  /// {@tool dartpad}
+  /// This sample demonstrates how to implement a custom app bar shape for the
+  /// [shape] property.
+  ///
+  /// ** See code in examples/api/lib/material/app_bar/app_bar.4.dart **
+  /// {@end-tool}
   /// See also:
   ///
   ///  * [elevation], which defines the size of the shadow below the app bar.