Fix: showDatePicker should have a simple example in the docs (#156196)

This PR introduces a basic example of how to use the `showDatePicker` function. The purpose of this PR is to simplify the onboarding process for new Flutter developers by providing a straightforward demonstration of handling the asynchronous Future returned by the showDatePicker. This will help users unfamiliar with the intricacies of asynchronous operations in Flutter.

Fixes #156157

examples/api/lib/material/date_picker/show_date_picker.1.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.
+
+import 'package:flutter/material.dart';
+
+/// Flutter code sample for basic [showDatePicker].
+
+void main() => runApp(const DatePickerApp());
+
+class DatePickerApp extends StatelessWidget {
+  const DatePickerApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(title: const Text('showDatePicker Example')),
+        body: const Center(child: DatePickerExample()),
+      ),
+    );
+  }
+}
+
+class DatePickerExample extends StatefulWidget {
+  const DatePickerExample({super.key});
+
+  @override
+  State<DatePickerExample> createState() => _DatePickerExampleState();
+}
+
+class _DatePickerExampleState extends State<DatePickerExample> {
+  DateTime? selectedDate;
+
+  Future<void> _selectDate() async {
+    final DateTime? pickedDate = await showDatePicker(
+      context: context,
+      initialDate: DateTime(2021, 7, 25),
+      firstDate: DateTime(2021),
+      lastDate: DateTime(2022),
+    );
+
+    setState(() {
+      selectedDate = pickedDate;
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      spacing: 20,
+      children: <Widget>[
+        Text(
+          selectedDate != null
+            ? '${selectedDate!.day}/${selectedDate!.month}/${selectedDate!.year}'
+            : 'No date selected',
+        ),
+        OutlinedButton(
+          onPressed: _selectDate,
+          child: const Text('Select Date'),
+        ),
+      ],
+    );
+  }
+}

examples/api/test/material/date_picker/show_date_picker.1_test.dart

@@ -0,0 +1,47 @@
+// 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/date_picker/show_date_picker.1.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('Can show date picker', (WidgetTester tester) async {
+    const String datePickerTitle = 'Select date';
+    const String initialDate = 'Sun, Jul 25';
+
+    await tester.pumpWidget(const example.DatePickerApp());
+
+    // The date picker is not shown initially.
+    expect(find.text(datePickerTitle), findsNothing);
+    expect(find.text(initialDate), findsNothing);
+
+    expect(find.text('No date selected'), findsOneWidget);
+    expect(find.byType(OutlinedButton), findsOneWidget);
+
+    // Tap the button to show the date picker.
+    await tester.tap(find.byType(OutlinedButton));
+    await tester.pumpAndSettle();
+
+    // The initial date is shown.
+    expect(find.text(datePickerTitle), findsOneWidget);
+    expect(find.text(initialDate), findsOneWidget);
+
+    // Tap another date to select it.
+    await tester.tap(find.text('30'));
+    await tester.pumpAndSettle();
+
+    // The selected date is shown.
+    expect(find.text(datePickerTitle), findsOneWidget);
+    expect(find.text('Fri, Jul 30'), findsOneWidget);
+
+     // Tap OK to confirm the selection and close the date picker.
+    await tester.tap(find.text('OK'));
+    await tester.pumpAndSettle();
+
+    // The date picker is closed and the selected date is shown.
+    expect(find.text(datePickerTitle), findsNothing);
+    expect(find.text('30/7/2021'), findsOneWidget);
+  });
+}

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

@@ -156,6 +156,13 @@ const double _fontSizeToScale = 14.0;
 ///
 /// {@macro flutter.widgets.RawDialogRoute}
 ///
+/// {@tool dartpad}
+/// This sample demonstrates how to create a basic date picker.
+/// Tapping the button displays a date picker which returns the selected date.
+///
+/// ** See code in examples/api/lib/material/date_picker/show_date_picker.1.dart **
+/// {@end-tool}
+///
 /// ### State Restoration
 ///
 /// Using this method will not enable state restoration for the date picker.