MiTimePicker

The MiTimePicker component is a stateless Flutter widget that provides a user interface for selecting a time. It utilizes Flutter's showTimePicker to display a time selection dialog and integrates with the application's data binding and theming. This component is designed for forms and settings where users need to input a specific time.

Overview

MiTimePicker simplifies time input by:

• Time Picker Dialog: Opens a native Flutter showTimePicker dialog when the text field is tapped, allowing users to visually select a time.
• Time Formatting: Supports both 12-hour (AM/PM) and 24-hour time formats, configurable via a parameter.
• Data Binding: Integrates with the application's data model through data binding, allowing the selected time to be easily stored and retrieved.
• Input Validation: Includes built-in validation capabilities, such as required field validation.
• Customizable Appearance: Offers various styling options, including label placement, font size, border styling (color, radius, roundness), and fill color, to match the application's theme.
• Optional onChanged Action: Triggers an action (e.g., updating data or performing an API call) when the selected time changes.
• Text Editing Controller & Focus Node: Provides access to a TextEditingController and FocusNode for advanced programmatic control of the input field.

Component Name: timePicker

JSON key: "component": "timePicker".

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
format	String	String	Time Format: Specifies the format of the time displayed in the text field and picker. Accepted values are "12hr" for 12-hour format (with AM/PM) and "24hr" for 24-hour format.	"12hr"	Yes	No
label	String	String	Label Text: Label displayed next to or above the time picker input field, depending on labelBehavior.	null	Yes	No
labelBehavior	String	String	Label Behavior: Determines the placement of the label. Accepted values are "inline" (label inside the input field as a placeholder/floating label) or "top" (label positioned above the input field).	"inline"	Yes	No
fontSize	num	double	Font Size: Font size for the label and the text in the time picker input field.	15.0	Yes	No
value	String	String	Value Key: Key to bind the selected time value to a specific location in the application's data model. This value is updated when a time is selected. The time is stored in ISO time format (HH:mm:ss).	null	Yes	No
fillColor	String	Color	Fill Color: Background color of the time picker input field.	null	Yes	No
roundBorders	bool	bool	Round Borders: If true, the time picker input field will have fully rounded borders (circular ends).	false	Yes	No
borderRadius	num	double	Border Radius: Border radius for the corners of the time picker input field. Only applicable if roundBorders is false.	8.0	Yes	No
borderColor	String	Color	Border Color: Color of the border of the time picker input field in its normal (unfocused) state.	Theme's outline color or Colors.black	Yes	No
focusBorderColor	String	Color	Focus Border Color: Color of the border of the time picker input field when it is focused.	Theme's accent color or Colors.black	Yes	No
isRequired	bool	bool	Is Required: If true, indicates that time selection is mandatory. An asterisk (*) may be displayed next to the label, and validation will fail if no time is selected.	false	Yes	No
enabled	bool	bool	Enabled: If true (default), the time picker input is enabled and interactive. If false, it is disabled and non-interactive.	true	Yes	No
onChangedAction	Map	Map	On Changed Action (Optional): JSON action to be invoked when the selected time changes (i.e., when a time is picked from the dialog). This can be used to trigger data updates, API calls, or other actions in response to time selection. Should be a standard action configuration as used with invokeAction.	null	Yes	No
validator	Function	String? Function(String?)?	Custom Validator Function (Optional): A custom Flutter validator function that can be provided for more complex validation logic. It takes the input value as a string and returns an error message string if validation fails, or null if it passes. This parameter is for programmatic validator injection and is typically not set directly via JSON, but through code when using MiTimePicker programmatically.	null	Yes	No
onChanged	Function	void Function(String?)?	On Changed Callback (Optional): A callback function invoked when the selected time changes. It receives the selected time in ISO format (HH:mm:ss) as a string argument. Similar to validator, this is for programmatic callback injection and is typically set via code, not JSON.	null	Yes	No
controller	TextEditingController	TextEditingController?	Text Editing Controller (Optional): An optional TextEditingController to manage the text field's content programmatically. Usually created internally by the component, but can be provided externally for specific control needs.	null (internally managed)	Yes	No
focusNode	FocusNode	FocusNode?	Focus Node (Optional): An optional FocusNode to manage the focus state of the text field programmatically. Typically managed internally, but can be externally provided for advanced focus control.	null (internally managed)	Yes	No
padding	List<num>	EdgeInsets	Padding: Padding around the MiTimePicker widget. Inherited from MiStatelessWidget.	null	Yes	No
margin	List<num>	EdgeInsets	Margin: Margin around the MiTimePicker widget. Inherited from MiStatelessWidget.	null	Yes	No
alignment	String	AlignmentGeometry	Alignment: Alignment of the MiTimePicker widget within its parent. Inherited from MiStatelessWidget.	"topLeft"	Yes	No
color	String	Color	Color: Background color of the container for the MiTimePicker widget. Inherited from MiStatelessWidget.	null	Yes	No
width	num	double	Width: Fixed width of the MiTimePicker widget. Inherited from MiStatelessWidget.	null	Yes	No
height	num	double	Height: Fixed height of the MiTimePicker widget. Inherited from MiStatelessWidget.	null	Yes	No

Note:

• Time Selection Flow: Tapping the MiTimePicker input field opens a time picker dialog. Once a time is selected and confirmed in the dialog, the selected time is formatted according to the format parameter and displayed in the text field. Simultaneously, if a value key is provided, the selected time in ISO format (HH:mm:ss) is updated in the application's data at the location specified by the value key.
• ISO Time Format: The time value is stored in the data model in ISO 8601 time format (HH:mm:ss), regardless of the display format (12hr or 24hr).
• Validation: Basic validation for required fields is supported via the isRequired parameter.
• Label Placement: The labelBehavior parameter offers flexibility in label positioning, allowing labels to be inline (as placeholders or floating labels within the input) or positioned above the input field.
• Styling Flexibility: MiTimePicker provides extensive styling options via parameters like fillColor, roundBorders, borderRadius, borderColor, focusBorderColor, and fontSize, allowing developers to visually customize the component to fit various design requirements.
• Event Handling: The onChangedAction parameter enables triggering custom actions upon time selection, making it possible to integrate time changes with application logic seamlessly. The onChanged and validator parameters offer programmatic access to callbacks and validators for more complex handling within Flutter code.

Example JSON Configuration

{
  "component": "timePicker",
  "label": "Event Time",
  "value": "${EVENT_DETAILS.TIME}",
  "format": "12hr",
  "isRequired": true,
  "roundBorders": true,
  "borderColor": "primary",
  "focusBorderColor": "accent",
  "margin": [0, 0, 0, 16]
}

Explanation of Example:

• "component": "timePicker": Specifies the component as MiTimePicker.
• "label": "Event Time": Sets the label text to "Event Time", which will be displayed inline (as default labelBehavior is "inline").
• "value": "${EVENT_DETAILS.TIME}": Data binds the selected time value to the TIME property within the EVENT_DETAILS data object.
• "format": "12hr": Configures the time to be displayed and selected in 12-hour format (e.g., 02:30 PM).
• "isRequired": true: Makes time selection a required field; validation will ensure a time is picked.
• "roundBorders": true: Sets the input field to have fully rounded borders.
• "borderColor": "primary": Sets the border color to the application's primary theme color in the normal state.
• "focusBorderColor": "accent": Sets the border color to the accent theme color when the input is focused.
• "margin": [0, 0, 0, 16]: Adds a bottom margin of 16 logical pixels to the time picker for spacing.