Allow empty initial time when using text input mode in showTimePicker dialog (flutter#172847)

Added ability to allow empty initial time when using text input mode in
showTimePicker dialog flutter#169131

- [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.

---------

Co-authored-by: Tong Mu <[email protected]>

Author: azatech

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

@@ -1636,6 +1636,7 @@ class _TimePickerInput extends StatefulWidget {
     required this.helpText,
     required this.autofocusHour,
     required this.autofocusMinute,
+    required this.emptyInitialTime,
     this.restorationId,
   });
 
@@ -1666,6 +1667,13 @@ class _TimePickerInput extends StatefulWidget {
   /// from the surrounding [RestorationScope] using the provided restoration ID.
   final String? restorationId;
 
+  /// If true and [TimePickerEntryMode.input] is used, hour and minute fields
+  /// start empty instead of using [initialSelectedTime].
+  ///
+  /// Useful when users prefer manual input without clearing pre-filled values.
+  /// Ignored in dial mode.
+  final bool emptyInitialTime;
+
   @override
   _TimePickerInputState createState() => _TimePickerInputState();
 }
@@ -1851,6 +1859,7 @@ class _TimePickerInputState extends State<_TimePickerInput> with RestorationMixi
                               onSavedSubmitted: _handleHourSavedSubmitted,
                               onChanged: _handleHourChanged,
                               hourLabelText: widget.hourLabelText,
+                              emptyInitialTime: widget.emptyInitialTime,
                             ),
                           ),
                           if (!hourHasError.value && !minuteHasError.value)
@@ -1885,6 +1894,7 @@ class _TimePickerInputState extends State<_TimePickerInput> with RestorationMixi
                               validator: _validateMinute,
                               onSavedSubmitted: _handleMinuteSavedSubmitted,
                               minuteLabelText: widget.minuteLabelText,
+                              emptyInitialTime: widget.emptyInitialTime,
                             ),
                           ),
                           if (!hourHasError.value && !minuteHasError.value)
@@ -1935,6 +1945,7 @@ class _HourTextField extends StatelessWidget {
     required this.onSavedSubmitted,
     required this.onChanged,
     required this.hourLabelText,
+    required this.emptyInitialTime,
     this.restorationId,
   });
 
@@ -1947,6 +1958,7 @@ class _HourTextField extends StatelessWidget {
   final ValueChanged<String> onChanged;
   final String? hourLabelText;
   final String? restorationId;
+  final bool emptyInitialTime;
 
   @override
   Widget build(BuildContext context) {
@@ -1960,6 +1972,7 @@ class _HourTextField extends StatelessWidget {
       semanticHintText: hourLabelText ?? MaterialLocalizations.of(context).timePickerHourLabel,
       validator: validator,
       onSavedSubmitted: onSavedSubmitted,
+      emptyInitialTime: emptyInitialTime,
       onChanged: onChanged,
     );
   }
@@ -1974,6 +1987,7 @@ class _MinuteTextField extends StatelessWidget {
     required this.validator,
     required this.onSavedSubmitted,
     required this.minuteLabelText,
+    required this.emptyInitialTime,
     this.restorationId,
   });
 
@@ -1985,6 +1999,7 @@ class _MinuteTextField extends StatelessWidget {
   final ValueChanged<String?> onSavedSubmitted;
   final String? minuteLabelText;
   final String? restorationId;
+  final bool emptyInitialTime;
 
   @override
   Widget build(BuildContext context) {
@@ -1997,6 +2012,7 @@ class _MinuteTextField extends StatelessWidget {
       style: style,
       semanticHintText: minuteLabelText ?? MaterialLocalizations.of(context).timePickerMinuteLabel,
       validator: validator,
+      emptyInitialTime: emptyInitialTime,
       onSavedSubmitted: onSavedSubmitted,
     );
   }
@@ -2013,6 +2029,7 @@ class _HourMinuteTextField extends StatefulWidget {
     required this.validator,
     required this.onSavedSubmitted,
     this.restorationId,
+    required this.emptyInitialTime,
     this.onChanged,
   });
 
@@ -2026,6 +2043,7 @@ class _HourMinuteTextField extends StatefulWidget {
   final ValueChanged<String?> onSavedSubmitted;
   final ValueChanged<String>? onChanged;
   final String? restorationId;
+  final bool emptyInitialTime;
 
   @override
   _HourMinuteTextFieldState createState() => _HourMinuteTextFieldState();
@@ -2058,9 +2076,12 @@ class _HourMinuteTextFieldState extends State<_HourMinuteTextField> with Restora
     super.didChangeDependencies();
     // Only set the text value if it has not been populated with a localized
     // version yet.
+    // If emptyInitialTime is true, set it to an empty string to indicate no
+    // initial time.
     if (!controllerHasBeenSet.value) {
       controllerHasBeenSet.value = true;
-      controller.value.value = TextEditingValue(text: _formattedValue);
+      final String initialTextValue = widget.emptyInitialTime ? '' : _formattedValue;
+      controller.value.value = TextEditingValue(text: initialTextValue);
     }
   }
 
@@ -2113,7 +2134,8 @@ class _HourMinuteTextFieldState extends State<_HourMinuteTextField> with Restora
     ).applyDefaults(inputDecorationTheme);
     // Remove the hint text when focused because the centered cursor
     // appears odd above the hint text.
-    final String? hintText = focusNode.hasFocus ? null : _formattedValue;
+    // Clear the hint text when emptyInitialTime is true.
+    final String? hintText = focusNode.hasFocus || widget.emptyInitialTime ? null : _formattedValue;
 
     // Because the fill color is specified in both the inputDecorationTheme and
     // the TimePickerTheme, if there's one in the user's input decoration theme,
@@ -2213,6 +2235,7 @@ class TimePickerDialog extends StatefulWidget {
     this.onEntryModeChanged,
     this.switchToInputEntryModeIcon,
     this.switchToTimerEntryModeIcon,
+    this.emptyInitialInput = false,
   });
 
   /// The time initially selected when the dialog is shown.
@@ -2279,6 +2302,12 @@ class TimePickerDialog extends StatefulWidget {
   /// {@macro flutter.material.time_picker.switchToTimerEntryModeIcon}
   final Icon? switchToTimerEntryModeIcon;
 
+  /// If true and entry mode is [TimePickerEntryMode.input], the hour and minute
+  /// fields will be empty on start instead of pre-filled with [initialTime].
+  ///
+  /// Has no effect in dial mode.
+  final bool emptyInitialInput;
+
   @override
   State<TimePickerDialog> createState() => _TimePickerDialogState();
 }
@@ -2617,6 +2646,7 @@ class _TimePickerDialogState extends State<TimePickerDialog> with RestorationMix
                               onEntryModeChanged: _handleEntryModeChanged,
                               switchToInputEntryModeIcon: widget.switchToInputEntryModeIcon,
                               switchToTimerEntryModeIcon: widget.switchToTimerEntryModeIcon,
+                              emptyInitialInput: widget.emptyInitialInput,
                             ),
                           );
                           if (_entryMode.value != TimePickerEntryMode.input &&
@@ -2661,6 +2691,7 @@ class _TimePicker extends StatefulWidget {
     this.onEntryModeChanged,
     this.switchToInputEntryModeIcon,
     this.switchToTimerEntryModeIcon,
+    required this.emptyInitialInput,
   });
 
   /// Optionally provide your own text for the help text at the top of the
@@ -2735,6 +2766,9 @@ class _TimePicker extends StatefulWidget {
   /// {@macro flutter.material.time_picker.switchToTimerEntryModeIcon}
   final Icon? switchToTimerEntryModeIcon;
 
+  /// If true, input fields start empty in input mode.
+  final bool emptyInitialInput;
+
   @override
   State<_TimePicker> createState() => _TimePickerState();
 }
@@ -2996,6 +3030,7 @@ class _TimePickerState extends State<_TimePicker> with RestorationMixin {
               autofocusHour: _autofocusHour.value,
               autofocusMinute: _autofocusMinute.value,
               restorationId: 'time_picker_input',
+              emptyInitialTime: widget.emptyInitialInput,
             ),
           ],
         );
@@ -3148,6 +3183,7 @@ Future<TimeOfDay?> showTimePicker({
   Orientation? orientation,
   Icon? switchToInputEntryModeIcon,
   Icon? switchToTimerEntryModeIcon,
+  bool emptyInitialInput = false,
 }) async {
   assert(debugCheckHasMaterialLocalizations(context));
 
@@ -3164,6 +3200,7 @@ Future<TimeOfDay?> showTimePicker({
     onEntryModeChanged: onEntryModeChanged,
     switchToInputEntryModeIcon: switchToInputEntryModeIcon,
     switchToTimerEntryModeIcon: switchToTimerEntryModeIcon,
+    emptyInitialInput: emptyInitialInput,
   );
   return showDialog<TimeOfDay>(
     context: context,

packages/flutter/test/material/time_picker_test.dart

@@ -2273,6 +2273,89 @@ void main() {
         expect(result, equals(const TimeOfDay(hour: 6, minute: 45)));
       });
     });
+
+    group('Time picker - emptyInitialInput (${materialType.name})', () {
+      testWidgets('Fields are empty and show correct hints when emptyInitialInput is true', (
+        WidgetTester tester,
+      ) async {
+        await startPicker(
+          tester,
+          (_) {},
+          entryMode: TimePickerEntryMode.input,
+          materialType: materialType,
+          emptyInitialInput: true,
+        );
+        await tester.pump();
+
+        final List<TextField> textFields = tester
+            .widgetList<TextField>(find.byType(TextField))
+            .toList();
+
+        expect(textFields[0].controller?.text, isEmpty); // hour
+        expect(textFields[1].controller?.text, isEmpty); // minute
+        expect(textFields[0].decoration?.hintText, isNull);
+        expect(textFields[1].decoration?.hintText, isNull);
+        await finishPicker(tester);
+      });
+
+      testWidgets('User sets hour/minute after initially empty fields', (
+        WidgetTester tester,
+      ) async {
+        late TimeOfDay result;
+        await startPicker(
+          tester,
+          (TimeOfDay? time) {
+            result = time!;
+          },
+          entryMode: TimePickerEntryMode.input,
+          materialType: materialType,
+          emptyInitialInput: true,
+        );
+
+        final List<TextField> textFields = tester
+            .widgetList<TextField>(find.byType(TextField))
+            .toList();
+
+        expect(textFields[0].controller?.text, isEmpty); // hour
+        expect(textFields[1].controller?.text, isEmpty); // minute
+        expect(textFields[0].decoration?.hintText, isNull);
+        expect(textFields[1].decoration?.hintText, isNull);
+
+        await tester.enterText(find.byType(TextField).first, '11');
+        await tester.enterText(find.byType(TextField).last, '30');
+        await finishPicker(tester);
+
+        expect(result, equals(const TimeOfDay(hour: 11, minute: 30)));
+      });
+
+      testWidgets('User overrides default values when emptyInitialInput is false', (
+        WidgetTester tester,
+      ) async {
+        late TimeOfDay result;
+        await startPicker(
+          tester,
+          (TimeOfDay? time) {
+            result = time!;
+          },
+          entryMode: TimePickerEntryMode.input,
+          materialType: materialType,
+        );
+
+        final List<TextField> textFields = tester
+            .widgetList<TextField>(find.byType(TextField))
+            .toList();
+
+        expect(textFields[0].controller?.text, '7'); // hour
+        expect(textFields[1].controller?.text, '00'); // minute
+
+        await tester.enterText(find.byType(TextField).first, '8');
+        await tester.enterText(find.byType(TextField).last, '15');
+        await tester.pump();
+        await finishPicker(tester);
+
+        expect(result, equals(const TimeOfDay(hour: 8, minute: 15)));
+      });
+    });
   }
 
   testWidgets('Material3 - Time selector separator default text style', (
@@ -2569,13 +2652,15 @@ class _TimePickerLauncher extends StatefulWidget {
     this.restorationId,
     this.cancelText,
     this.confirmText,
+    required this.emptyInitialInput,
   });
 
   final ValueChanged<TimeOfDay?> onChanged;
   final TimePickerEntryMode entryMode;
   final String? restorationId;
   final String? cancelText;
   final String? confirmText;
+  final bool emptyInitialInput;
 
   @override
   _TimePickerLauncherState createState() => _TimePickerLauncherState();
@@ -2653,6 +2738,7 @@ class _TimePickerLauncherState extends State<_TimePickerLauncher> with Restorati
                       context: context,
                       initialTime: const TimeOfDay(hour: 7, minute: 0),
                       initialEntryMode: widget.entryMode,
+                      emptyInitialInput: widget.emptyInitialInput,
                     ),
                   );
                 } else {
@@ -2682,6 +2768,7 @@ Future<Offset?> startPicker(
   MaterialType? materialType,
   String? cancelText,
   String? confirmText,
+  bool emptyInitialInput = false,
 }) async {
   await tester.pumpWidget(
     MaterialApp(
@@ -2694,6 +2781,7 @@ Future<Offset?> startPicker(
         restorationId: restorationId,
         cancelText: cancelText,
         confirmText: confirmText,
+        emptyInitialInput: emptyInitialInput,
       ),
     ),
   );