Formatters & Validators #17

Author: BirjuVachhani

lib/src/api/models/text_input_validator_model.dart

@@ -7,6 +7,178 @@ import '../mixins.dart';
 
 part 'text_input_validator_model.g.dart';
 
+/// Represents an action to perform when the user presses the action button on
+/// the keyboard.
+enum TextInputActionC {
+  /// Logical meaning: There is no relevant input action for the current input
+  /// source, e.g., [TextField].
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_NONE". The keyboard setup
+  /// is decided by the OS. The keyboard will likely show a return key.
+  ///
+  /// iOS: iOS does not have a keyboard return type of "none." It is
+  /// inappropriate to choose this [TextInputAction] when running on iOS.
+  none,
+
+  /// Logical meaning: Let the OS decide which action is most appropriate.
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_UNSPECIFIED". The OS chooses
+  /// which keyboard action to display. The decision will likely be a done
+  /// button or a return key.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyDefault". The title displayed in
+  /// the action button is "return".
+  unspecified,
+
+  /// Logical meaning: The user is done providing input to a group of inputs
+  /// (like a form). Some kind of finalization behavior should now take place.
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_DONE". The OS displays a
+  /// button that represents completion, e.g., a checkmark button.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyDone". The title displayed in the
+  /// action button is "Done".
+  done,
+
+  /// Logical meaning: The user has entered some text that represents a
+  /// destination, e.g., a restaurant name. The "go" button is intended to take
+  /// the user to a part of the app that corresponds to this destination.
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_GO". The OS displays a
+  /// button that represents taking "the user to the target of the text they
+  /// typed", e.g., a right-facing arrow button.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyGo". The title displayed in the
+  /// action button is "Go".
+  go,
+
+  /// Logical meaning: Execute a search query.
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_SEARCH". The OS displays a
+  /// button that represents a search, e.g., a magnifying glass button.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeySearch". The title displayed in the
+  /// action button is "Search".
+  search,
+
+  /// Logical meaning: Sends something that the user has composed, e.g., an
+  /// email or a text message.
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_SEND". The OS displays a
+  /// button that represents sending something, e.g., a paper plane button.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeySend". The title displayed in the
+  /// action button is "Send".
+  send,
+
+  /// Logical meaning: The user is done with the current input source and wants
+  /// to move to the next one.
+  ///
+  /// Moves the focus to the next focusable item in the same [FocusScope].
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_NEXT". The OS displays a
+  /// button that represents moving forward, e.g., a right-facing arrow button.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyNext". The title displayed in the
+  /// action button is "Next".
+  next,
+
+  /// Logical meaning: The user wishes to return to the previous input source
+  /// in the group, e.g., a form with multiple [TextField]s.
+  ///
+  /// Moves the focus to the previous focusable item in the same [FocusScope].
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_PREVIOUS". The OS displays a
+  /// button that represents moving backward, e.g., a left-facing arrow button.
+  ///
+  /// iOS: iOS does not have a keyboard return type of "previous." It is
+  /// inappropriate to choose this [TextInputAction] when running on iOS.
+  previous,
+
+  /// Logical meaning: In iOS apps, it is common for a "Back" button and
+  /// "Continue" button to appear at the top of the screen. However, when the
+  /// keyboard is open, these buttons are often hidden off-screen. Therefore,
+  /// the purpose of the "Continue" return key on iOS is to make the "Continue"
+  /// button available when the user is entering text.
+  ///
+  /// Historical context aside, [TextInputAction.continueAction] can be used any
+  /// time that the term "Continue" seems most appropriate for the given action.
+  ///
+  /// Android: Android does not have an IME input type of "continue." It is
+  /// inappropriate to choose this [TextInputAction] when running on Android.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyContinue". The title displayed in the
+  /// action button is "Continue". This action is only available on iOS 9.0+.
+  ///
+  /// The reason that this value has "Action" post-fixed to it is because
+  /// "continue" is a reserved word in Dart, as well as many other languages.
+  continueAction,
+
+  /// Logical meaning: The user wants to join something, e.g., a wireless
+  /// network.
+  ///
+  /// Android: Android does not have an IME input type of "join." It is
+  /// inappropriate to choose this [TextInputAction] when running on Android.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyJoin". The title displayed in the
+  /// action button is "Join".
+  join,
+
+  /// Logical meaning: The user wants routing options, e.g., driving directions.
+  ///
+  /// Android: Android does not have an IME input type of "route." It is
+  /// inappropriate to choose this [TextInputAction] when running on Android.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyRoute". The title displayed in the
+  /// action button is "Route".
+  route,
+
+  /// Logical meaning: Initiate a call to emergency services.
+  ///
+  /// Android: Android does not have an IME input type of "emergencyCall." It is
+  /// inappropriate to choose this [TextInputAction] when running on Android.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyEmergencyCall". The title displayed
+  /// in the action button is "Emergency Call".
+  emergencyCall,
+
+  /// Logical meaning: Insert a newline character in the focused text input,
+  /// e.g., [TextField].
+  ///
+  /// Android: Corresponds to Android's "IME_ACTION_NONE". The OS displays a
+  /// button that represents a new line, e.g., a carriage return button.
+  ///
+  /// iOS: Corresponds to iOS's "UIReturnKeyDefault". The title displayed in the
+  /// action button is "return".
+  ///
+  /// The term [TextInputAction.newline] exists in Flutter but not in Android
+  /// or iOS. The reason for introducing this term is so that developers can
+  /// achieve the common result of inserting new lines without needing to
+  /// understand the various IME actions on Android and return keys on iOS.
+  /// Thus, [TextInputAction.newline] is a convenience term that alleviates the
+  /// need to understand the underlying platforms to achieve this common behavior.
+  newline;
+
+  /// Displayable string representation of the enum value.
+  String get prettify {
+    return switch (this) {
+      TextInputActionC.none => 'None',
+      TextInputActionC.unspecified => 'Unspecified',
+      TextInputActionC.done => 'Done',
+      TextInputActionC.go => 'Go',
+      TextInputActionC.search => 'Search',
+      TextInputActionC.send => 'Send',
+      TextInputActionC.next => 'Next',
+      TextInputActionC.previous => 'Previous',
+      TextInputActionC.continueAction => 'Continue',
+      TextInputActionC.join => 'Join',
+      TextInputActionC.route => 'Route',
+      TextInputActionC.emergencyCall => 'Emergency Call',
+      TextInputActionC.newline => 'New-line',
+    };
+  }
+}
+
 /// Used to configure the auto validation of [FormField] and [Form] widgets.
 enum AutovalidateModeC {
   /// No auto validation will occur.

lib/src/api/nodes/text_field_node.dart

@@ -218,6 +218,10 @@ class TextFieldProperties with SerializableMixin, EquatableMixin {
   /// device's autofill service.
   Set<TextInputAutofillHints> autofillHints;
 
+  /// The action the keyboard should take when the user presses the action
+  /// button on the keyboard.
+  TextInputActionC textInputAction;
+
   /// Creates a [TextFieldProperties] instance with the given data.
   TextFieldProperties({
     this.autoCorrect = true,
@@ -249,6 +253,7 @@ class TextFieldProperties with SerializableMixin, EquatableMixin {
     this.validator = const NoneTextInputValidatorModel(),
     this.autovalidateMode = AutovalidateModeC.onUserInteraction,
     this.autofillHints = const {},
+    this.textInputAction = TextInputActionC.none,
   })  : inputStyle = inputStyle ??
             StartEndProp.general(fontSize: 14, fills: [PaintModel.blackPaint]),
         decoration = decoration ?? InputDecorationModel();
@@ -285,6 +290,7 @@ class TextFieldProperties with SerializableMixin, EquatableMixin {
     TextInputValidatorModel? validator,
     Set<TextInputAutofillHints>? autofillHints,
     AutovalidateModeC? autovalidateMode,
+    TextInputActionC? textInputAction,
   }) {
     return TextFieldProperties(
       autoCorrect: autoCorrect ?? this.autoCorrect,
@@ -317,6 +323,7 @@ class TextFieldProperties with SerializableMixin, EquatableMixin {
       validator: validator ?? this.validator,
       autofillHints: autofillHints ?? this.autofillHints,
       autovalidateMode: autovalidateMode ?? this.autovalidateMode,
+      textInputAction: textInputAction ?? this.textInputAction,
     );
   }
 
@@ -358,5 +365,6 @@ class TextFieldProperties with SerializableMixin, EquatableMixin {
         validator,
         autofillHints,
         autovalidateMode,
+        textInputAction,
       ];
 }