Add a ReorderableListView example with cards + cleanup existing tests…

… (#126155)

## Description

This PR adds one `ReorderableListView` example to demonstrate how `proxyDecorator` can be used to animate cards elevation.

https://user-images.githubusercontent.com/840911/236468570-d2b33ab3-6b6d-4f8d-90de-778dcf1ad8ce.mp4

For motivation, see flutter/flutter#124729 (comment).

## Related Issue

Fixes flutter/flutter#124729

## Tests

Adds 1 tests.

This PR also moves some misplaced example tests from `examples/api/test/reorderable_list` to `examples/api/test/material/reorderable_list` (and replaces two existing ones).

examples/api/lib/material/reorderable_list/reorderable_list_view.2.dart

@@ -0,0 +1,94 @@
+// 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 'dart:ui';
+
+import 'package:flutter/material.dart';
+
+/// Flutter code sample for [ReorderableListView].
+
+void main() => runApp(const ReorderableApp());
+
+class ReorderableApp extends StatelessWidget {
+  const ReorderableApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      theme: ThemeData(useMaterial3: true),
+      home: Scaffold(
+        appBar: AppBar(title: const Text('ReorderableListView Sample')),
+        body: const ReorderableExample(),
+      ),
+    );
+  }
+}
+
+class ReorderableExample extends StatefulWidget {
+  const ReorderableExample({super.key});
+
+  @override
+  State<ReorderableExample> createState() => _ReorderableExampleState();
+}
+
+class _ReorderableExampleState extends State<ReorderableExample> {
+  final List<int> _items = List<int>.generate(50, (int index) => index);
+
+  @override
+  Widget build(BuildContext context) {
+    final Color oddItemColor = Colors.lime.shade100;
+    final Color evenItemColor = Colors.deepPurple.shade100;
+
+    final List<Card> cards = <Card>[
+      for (int index = 0; index < _items.length; index += 1)
+        Card(
+          key: Key('$index'),
+          color: _items[index].isOdd ? oddItemColor : evenItemColor,
+          child: SizedBox(
+            height: 80,
+            child: Center(
+              child: Text('Card ${_items[index]}'),
+            ),
+          ),
+        ),
+    ];
+
+    Widget proxyDecorator(Widget child, int index, Animation<double> animation) {
+      return AnimatedBuilder(
+        animation: animation,
+        builder: (BuildContext context, Widget? child) {
+          final double animValue = Curves.easeInOut.transform(animation.value);
+          final double elevation = lerpDouble(1, 6, animValue)!;
+          final double scale = lerpDouble(1, 1.02, animValue)!;
+          return Transform.scale(
+            scale: scale,
+            // Create a Card based on the color and the content of the dragged one
+            // and set its elevation to the animated value.
+            child: Card(
+              elevation: elevation,
+              color: cards[index].color,
+              child: cards[index].child,
+            ),
+          );
+        },
+        child: child,
+      );
+    }
+
+    return ReorderableListView(
+      padding: const EdgeInsets.symmetric(horizontal: 40),
+      proxyDecorator: proxyDecorator,
+      onReorder: (int oldIndex, int newIndex) {
+        setState(() {
+          if (oldIndex < newIndex) {
+            newIndex -= 1;
+          }
+          final int item = _items.removeAt(oldIndex);
+          _items.insert(newIndex, item);
+        });
+      },
+      children: cards,
+    );
+  }
+}

examples/api/test/material/reorderable_list/reorderable_list_view.0_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/gestures.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/reorderable_list/reorderable_list_view.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Content is reordered after a drag', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.ReorderableApp(),
+    );
+
+    bool item1IsBeforeItem2() {
+      final Iterable<Text> texts = tester.widgetList<Text>(find.byType(Text));
+      final List<String?> labels = texts.map((final Text text) => text.data).toList();
+      return labels.indexOf('Item 1') < labels.indexOf('Item 2');
+    }
+
+    expect(item1IsBeforeItem2(), true);
+
+    // Drag 'Item 1' after 'Item 4'.
+    final TestGesture drag = await tester.startGesture(tester.getCenter(find.text('Item 1')));
+    await tester.pump(kLongPressTimeout + kPressTimeout);
+    await tester.pumpAndSettle();
+    await drag.moveTo(tester.getCenter(find.text('Item 4')));
+    await drag.up();
+    await tester.pumpAndSettle();
+
+    expect(item1IsBeforeItem2(), false);
+  });
+}

examples/api/test/material/reorderable_list/reorderable_list_view.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/gestures.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/reorderable_list/reorderable_list_view.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Dragged item color is updated', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.ReorderableApp(),
+    );
+
+    final ThemeData theme = Theme.of(tester.element(find.byType(MaterialApp)));
+
+    // Dragged item is wrapped in a Material widget with correct color.
+    final TestGesture drag = await tester.startGesture(tester.getCenter(find.text('Item 1')));
+    await tester.pump(kLongPressTimeout + kPressTimeout);
+    await tester.pumpAndSettle();
+    final Material material = tester.widget<Material>(find.ancestor(
+      of: find.text('Item 1'),
+      matching: find.byType(Material),
+    ));
+    expect(material.color, theme.colorScheme.secondary);
+
+    // Ends the drag gesture.
+    await drag.moveTo(tester.getCenter(find.text('Item 4')));
+    await drag.up();
+    await tester.pumpAndSettle();
+  });
+}

examples/api/test/material/reorderable_list/reorderable_list_view.2_test.dart

@@ -0,0 +1,35 @@
+// 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/gestures.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/reorderable_list/reorderable_list_view.2.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Dragged Card is elevated', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.ReorderableApp(),
+    );
+
+    Card findCardOne() {
+      return tester.widget<Card>(find.ancestor(of: find.text('Card 1'), matching: find.byType(Card)));
+    }
+
+    // Card has default elevation when not dragged.
+    expect(findCardOne().elevation, null);
+
+    // Dragged card is elevated.
+    final TestGesture drag = await tester.startGesture(tester.getCenter(find.text('Card 1')));
+    await tester.pump(kLongPressTimeout + kPressTimeout);
+    await tester.pumpAndSettle();
+    expect(findCardOne().elevation, 6);
+
+    // After the drag gesture ends, the card elevation has default value.
+    await drag.moveTo(tester.getCenter(find.text('Card 4')));
+    await drag.up();
+    await tester.pumpAndSettle();
+    expect(findCardOne().elevation, null);
+  });
+}

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

@@ -34,18 +34,29 @@ import 'theme.dart';
 ///
 /// All list items must have a key.
 ///
-/// This example demonstrates using the [proxyDecorator] callback to customize
-/// the appearance of a list item while it's being dragged.
-/// {@tool dartpad}
+/// This example demonstrates using the [ReorderableListView.proxyDecorator] callback
+/// to customize the appearance of a list item while it's being dragged.
 ///
-/// While a drag is underway, the widget returned by the [proxyDecorator]
-/// serves as a "proxy" (a substitute) for the item in the list. The proxy is
-/// created with the original list item as its child. The [proxyDecorator]
-/// in this example is similar to the default one except that it changes the
+/// {@tool dartpad}
+/// While a drag is underway, the widget returned by the [ReorderableListView.proxyDecorator]
+/// callback serves as a "proxy" (a substitute) for the item in the list. The proxy is
+/// created with the original list item as its child. The [ReorderableListView.proxyDecorator]
+/// callback in this example is similar to the default one except that it changes the
 /// proxy item's background color.
 ///
 /// ** See code in examples/api/lib/material/reorderable_list/reorderable_list_view.1.dart **
 /// {@end-tool}
+///
+/// This example demonstrates using the [ReorderableListView.proxyDecorator] callback to
+/// customize the appearance of a [Card] while it's being dragged.
+///
+/// {@tool dartpad}
+/// The default [proxyDecorator] wraps the dragged item in a [Material] widget and animates
+/// its elevation. This example demonstrates how to use the [ReorderableListView.proxyDecorator]
+/// callback to update the dragged card elevation without inserted a new [Material] widget.
+///
+/// ** See code in examples/api/lib/material/reorderable_list/reorderable_list_view.2.dart **
+/// {@end-tool}
 class ReorderableListView extends StatefulWidget {
   /// Creates a reorderable list from a pre-built list of widgets.
   ///