From 3e9901dac92ccb4fe822191ee0fda10cb2cdaa89 Mon Sep 17 00:00:00 2001
From: Jiten Patel <jiten.pateljp2001@gmail.com>
Date: Tue, 22 Oct 2024 22:34:23 +0530
Subject: [PATCH] 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
---
 .../date_picker/show_date_picker.1.dart       | 66 +++++++++++++++++++
 .../date_picker/show_date_picker.1_test.dart  | 47 +++++++++++++
 .../flutter/lib/src/material/date_picker.dart |  7 ++
 3 files changed, 120 insertions(+)
 create mode 100644 examples/api/lib/material/date_picker/show_date_picker.1.dart
 create mode 100644 examples/api/test/material/date_picker/show_date_picker.1_test.dart

diff --git a/examples/api/lib/material/date_picker/show_date_picker.1.dart b/examples/api/lib/material/date_picker/show_date_picker.1.dart
new file mode 100644
index 00000000000..936ff4866e9
--- /dev/null
+++ b/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'),
+        ),
+      ],
+    );
+  }
+}
diff --git a/examples/api/test/material/date_picker/show_date_picker.1_test.dart b/examples/api/test/material/date_picker/show_date_picker.1_test.dart
new file mode 100644
index 00000000000..62741c919e1
--- /dev/null
+++ b/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);
+  });
+}
diff --git a/packages/flutter/lib/src/material/date_picker.dart b/packages/flutter/lib/src/material/date_picker.dart
index 9b170efb5f8..6366accd0dd 100644
--- a/packages/flutter/lib/src/material/date_picker.dart
+++ b/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.