• Date time input specification
  • Owned by
  • Requires approval from
  • Signed off by
  • Revision history
  • Overview
    • Acceptance criteria
  • User stories
  • Functionality
    • Custom input format
    • Custom display format
    • Keyboard navigation
    • End-user experience
    • Developer experience
  • API
    • igc-date-time-input
    • Properties
    • Methods
    • Events
    • Slots
    • CSS Shadow Parts
  • Assumptions and limitations
  • Test scenarios

Team: Codex

Radoslav Karaivanov

• | Date:

• Product Owner: Radoslav Mirchev | Date:
• Platform Architect: Damyan Petev | Date:

Version	Author	Date	Notes
1	Ivaylo Barakov	20-Mar-2022	First draft
1.01	Ivaylo Barakov	22-Jul-2022	Edit "Custom display format" section

A date time input is an input field that lets you set and edit the date and time in a chosen input element. The display and input formats are customizable, as well as min and max values.

1. Should provide a mask, specifying the date/time inputFormat and displayFormat
2. Should provide a prompt symbol for customizing the unfilled parts of the mask
3. Should support static symbols (literals) in the mask
4. Should support all the properties/API of the igc-input element where applicable
5. Should correctly manage and report its validation state, if any validation constraints or required positions are applied
6. Should be supported as a component which participates in an igc-form submission
7. Should support the following custom input formats

Developer stories:

As a developer I expect to be able to:

• define a mask specifying the date/time inputFormat and displayFormat
• use the mask as a placeholder if the property is not set
• specify the prompt character
• set predefined displayFormat in a simple manner - short, long, medium, full
• configure the editor as editable, read-only and disabled
• set a default date/time value
• specify if incrementing continues past the maximum and wraps around (by default it does) e.g. for minutes from 59 to 00 or just stays at it.
• set minValue and maxValue properties which control the validity of the input
• expect the editor to complete partially entered dates
• expect that the editor will clear invalid input on blur
• enable/disable the zero prefixes for dates/months/hours e.g. 9:03 or 09:03
• specify the step - spinDelta, at which the selected time part will be incremented/decremented

End user stories:

As an end user, I want:

• To be able to display date/time values based on a defined mask
• To be able to edit the date/time value in the editor
• To be able to paste or drag-and-drop dates from elsewhere into the input
• The fields that need to be filled, to be clearly indicated with prompt characters
• To see a placeholder text when the input is empty, suggesting me what to type in
• The editor to handle partial dates
• The editor to have buttons for incrementing/decrementing the currently selected date/time portion
• To be able to use the mouse wheel to spin date/time portions. The spinning should occur for the date/time portion where the caret currently is in the editor

A date time input is a text field that allows the user to set and edit the date and time in a chosen input element, controlled and filtered by a predefined mask. Helper text, placeholders, and visual states can be updated accordingly upon string input/interaction and data can be submitted.

Format	Description
d	Date, will be coerced with a leading zero while editing.
dd	Date with an explicitly set leading zero.
M	Month, will be coerced with a leading zero while editing.
MM	Month with an explicitly set leading zero.
yy	Short year format.
yyyy	Full year format.
h	Hours in 12-hour format, will be coerced with a leading zero while editing.
hh	Hours in 12-hour format with an explicitly set leading zero.
H	Hours in 24-hour format, will be coerced with a leading zero while editing.
HH	Hours in 24-hour format, with an explicitly set leading zero.
m	Minutes, will be coerced with a leading zero while editing.
mm	Minutes with an explicitly set leading zero.
tt	AM/PM section for 12-hour format.

The date time input exposes predefined formats for displaying date/time in various manners. All of the examples below are given in en-US locale.

Option	Example
short	7/17/22, 12:00 AM
medium	Jul 17, 2022, 12:00:00 AM
long	July 17, 2022 at 12:00:00 AM GMT+3
full	Sunday, July 17, 2022 at 12:00:00 AM Eastern European Summer Time
shortDate	7/17/22
mediumDate	Jul 17, 2022
longDate	July 17, 2022
fullDate	Sunday, July 17, 2022
shortTime	12:00 AM
mediumTime	12:00:00 AM
longTime	12:00:00 AM GMT+3
fullTime	12:00:00 AM Eastern European Summer Time

Furthermore, users can construct a displayFormat string using the supported symbols described in the following table.

Type	Format	Description	Example
Day of month	d	Minimum digits.	7, 17
	dd	Zero padded.	07, 17
Month	M	Minimum digits.	3, 10
	MM	Zero padded.	03, 10
	MMM	Abbreviated	Oct
	MMMM	Wide	October
	MMMMM	Narrow	O
Year	y	Numeric	2022
	yy	Two digit	22
	yyy	Numeric	2022
	yyyy	Numeric	2022
Hour 1-12	h	Minimum digits	1, 12
	hh	Zero padded	01, 12
Hour 1-24	H	Minimum digits	1, 23
	HH	Zero padded	01, 23
Minute	m	Minimum digits	1, 59
	mm	Zero padded	01, 59
Second	s	Minimum digits	1, 59
	ss	Zero padded	01, 59
Time Period	t	Abbreviated	AM, PM
	tt	Abbreviated	AM, PM
	ttt	Short	noon
	tttt	Long	noon
	ttttt	Narrow	n

Note: Many locales use the same time period string, irrespective of the format specified. Also, it has an effect only if a 12-hour clock is used.

Keys	Description
←	Move one character to the left
→	Move one character to the right
Home	Move to the beginning
End	Move to the end
Ctrl / Command + ←	Move to the beginning of the date/time section - current one or left one
Ctrl / Command + →	Move to the end of the date/time section - current on or right one
Focus on a date/time part + ↓	Decrements a date/time part
Focus on a date/time part + ↑	Increments a date/time part
Ctrl / Command + ;	Sets the current date/time as the value of the editor

TODO

TODO

Mixins: SizableMixin, EventEmitterMixin

Property	Attribute	Type	Default	Description
dir	dir	"ltr" | "rtl" | "auto"	"auto"	The direction attribute of the control.
label	label	string		The label for the control.
inputFormat	input-format	string		The date pattern to apply on the input.
placeholder	placeholder	string		Placeholder for the input.
prompt	prompt	string		The prompt symbol to use for unfilled parts of the mask.
locale	locale	string	"en"	The locale settings used in displayFormat.
displayFormat	display-format	string		The display date pattern of the editor.
size	size	"small" | "medium" | "large"	"medium"	Determines the size of the component.
value	value	Date		The value of the input.
minValue	min-value	Date		Sets the minimum value required for the editor to remain valid.
maxValue	max-value	Date		Sets the maximum value required for the editor to remain valid.
spinLoop	spin-loop	boolean	true	Loop over the currently spun segment.

Name	Type	Description
clear	(): void	Clears the input element of user input.
blur	(): void	Removes focus from the control.
focus	(options?: FocusOptions | undefined): void	Sets focus on the control.
stepUp	(datePart?: DatePart, delta?: number): void	Increments the current date/time portion.
stepDown	(datePart?: DatePart, delta?: number): void	Decrements the current date/time portion.
setCustomValidity	(message: string): void	Sets a custom validation message for the control. As long as message is not empty, the control is considered invalid.
setRangeText	(replacement: string, start: number, end: number, _selectMode?: "select" | "start" | "end" | "preserve"): void	Replaces the selected text in the control and re-applies the mask
setSelectionRange	(start: number, end: number, direction?: "none" | "backward" | "forward" | undefined): void	Sets the text selection range of the control

Event	Description
igcBlur	Emitted when the control loses focus
igcChange	Emitted when an alteration of the control's value is committed by the user
igcFocus	Emitted when the control gains focus
igcInput	Emitted when the control receives user input

Name	Description
helper-text	Renders content below the input
prefix	Renders content before the input
suffix	Renders content after the input

Part	Description
container	The main wrapper that holds all main input elements
helper-text	The helper text wrapper
input	The native input element
label	The native label element
prefix	The prefix wrapper
suffix	The suffix wrapper

• The igc-date-input does not expose a type attribute since it is always an input of type text
• Undo/redo behavior is currently not supported.

• Should correctly set default prompt, mask and placeholder values
• Should correctly update mask according to the input format
• Should correctly update mask according to the locale
• Should correctly use display format when defined
• Should correctly switch between pre-defined display formats
• Should correctly clear value on clear
• Should correctly increment/decrement
• Should initialize new date on stepUp/stepDown if value is empty
• Should correctly set value by providing an ISO string
• Should correctly increment/decrement different date/time parts based on spinDelta
• Should correctly increment/decrement different date/time parts based on spinLoop
• Should correctly increment/decrement with mouse wheel and the arrow buttons
• Should correctly fill the missing parts on blur if input is incomplete
• Should clear input on blur if value is an invalid date
• Should respect min/maxValue
• Should correctly set min/maxValue by providing an ISO string
• Should correctly switch between valid/invalid state when required