DateTime Editor Specification

Date Editor Specification

Revision History

Version	User	Date	Notes
0.1	Nikolay Alipiev	January 14, 2020	Initial Draft + Keyboard section
0.2	Nikolay Alipiev	January 16, 2020	Min and Max values
0.3	Nikolay Alipiev	January 17, 2020	Validation required
0.4	Nikolay Alipiev	January 17, 2020	Validation - preventing invalid input
0.5	Stefan Ivanov	January 21, 2020	User and Developer Stories
0.6	Boris Penkov	January 21, 2020	User and Developer Stories
0.7	Boris Penkov	January 22, 2020	User and Developer Stories
0.8	Ivaylo Ganchev	January 23, 2020	Adding test scenarios
0.9		January **, 2020

Nikolay Alipiev | Date:
Konstantin Dinev | Date:
Radoslav Mirchev | Date:

1. Overview

GitHub	Milestone	Issue#	Name
igniteui-angular		#6271	Separate date and time editing functionalities from igxDatePicker and igxTimePicker into a new directive

Objectives

2. User Scenarios

The date editor directive supports the following user scenarios:

As an end user

Story 1: I want to be able to visually identify what day is selected.
Story 2: I want to be able to increment/decrement the date/time section where my cursor currently is with the keyboard arrows up/down.
Story 3: I want to edit the date in the input when the date editor is editable.
Story 4: I want to clear the entered value in the input using a clear button.
Story 5: I want to set the current day and time in the editor via a shortcut (CTRL+; as it is in Excel).
Story 6: I want to have a visual cue about the portion of the time that is currently in focus through a subtle background coloring
Story 7: I want to have a visual cue about the portion of the time that is currently hovered by coloring the text accordingly
Story 8: On user interaction with the dialog/dropdown list, I expect that the input should always be focused, except in the case of outside click.
Story 9: I want to be able to select a date/time range via the date/time editor via a respective mask.
Story 10: If the text within the editor exceeds the editor's width I want it to show as many characters as possible, followed by "...".
Story 11: I want the editor to have visual buttons that can be used to increment/decrement the editor's currently selected part.
Story 12: I want the editor to display a "day/month/year" (ordered depending on the format) if I enter a value that is not in the specified min/max range. It should be based on the current date part that is edited. If the date is 12/12/2012 (dd/mm/yyyy) and the min date is 12/10/2012 and we enter 12/09/2012, the editor should display 12/month/2012. Similar functionality should apply for HH:mm:ss.
Story 13: I want to see a cue that tells me the date/time I've entered is invalid.

As a developer

Story 1: I want to be able to implement a date editor in my application.
Story 2: I want to be able to configure the editor as editable(default value), read-only and disabled.
Story 3: I expect to have keyboard navigation out of the box.
Story 4: I want to define a mask specifying the date/time format and separators.
Story 5: I want to have validation for min and max allowable date/time.
Story 6: I want to have validation for date/time formats e.g. 22/22/2020 is not a valid date
Story 7: I want to be able to set a default date/time value for the editor
Story 8: I want to be able to enable/disable(default) the spinning when incrementing/decrementing a time portion through a boolean option e.g. limitSpin.
Story 9: I want to be able to enable/disable the zero prefixes for dates/months/hours e.g. 9:03 or 09:03.
Story 10: I want to specify of 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.
Story 11: I want to have the date/time automatically set to the default value when the user clears it.
Story 12: I want to be able to bind ngModel to the range date picker.
Story 13: I want to be able to use the range date picker in Angular forms.
Story 13: I want to have a default min value for the editor.
Story 14: I want the editor to unobtrusively correct any invalid inputs that I enter.
Story 15: I want to be able to specify the step at which the selected date/time part will be incremented/decremented.
Story 16: I want to be able to toggle the enforcement of min and max properties during form validation.
Story 17: I want to be informed that the editor has been blurred, focused.
Story 18: I want to be informed when the editor's value has changed and I want to be able to access the new and old values through the event data.
Story 19: I want to be able to programmatically blur and focus the editor.
Story 20: I want to be able to set locale settings in a simple manner - shortDate, longDate, etc.
Story 21: I want to be able to validate the editor's state after a valid date has been entered; partial dates and empty date parts should result in an invalid state. This should apply for the time segment of the editor - since the initial time 00:00:00 is a valid state.

Acceptance criteria

All user stories must be satisfied.

Functionality

Date input or selection
Custom date display format
- List of date pattern is used:
- Y: year field without century and without leading zero Sample display value: 9 for 2009-06-21
- YY: year field without century and with leading zero Sample display value: 09 for 2009-06-21
- YYYY: year field with leading zeros Sample display value: 2009 for 2009-06-21
- M: month field as digit without leading zero Sample display value: 7 for 2009-07-21
- MM: month field as digit with leading zero Sample display value: 07 for 2009-07-21
- MMM: month field as short month name (up to 4 letters) Sample display value: Aug for 2017-08-21
- Short month name Full month name
  
  Jan January
  
  Feb February
  
  Mar March
  
  Apr April
  
  May May
  
  Jun June
  
  Jul July
  
  Aug August
  
  Sept September
  
  Oct October
  
  Nov November
  
  Dec December
- MMMM: month field as long month name Sample display value: August for 2017-08-21
- D: day of month field without leading zero Sample display value: 5 for 2017-08-05
- DD: day of month field with leading zero Sample display value: 05 for 2017-08-05
- DDD: day of the week as short name Sample display value: Thu for 2017-06-22
- Short weekday name Full weekday name
  
  Mon Monday
  
  Tue Tuesday
  
  Wed Wednesday
  
  Thu Thursday
  
  Fri Friday
  
  Sat Saturday
  
  Sun Sunday
- DDDD: day of the week as long name Sample display value: Friday for 2017-06-23
Date Validation - prevent invalid input issue
Date Validation (min/max check) – min and max day are settable. If manually inputted, the value is reverted to the set min/max. There is already an issue about that.
Date Validation (required) - issue
Incrementing/decrementing the date/time section where the cursor currently is via the keyboard:

3.1 Developer Experience

3.2 End user Experience

3.3 Keyboard Navigation

Navigation through different date editor sections should happen using the Arrow Left/Right keys, similar to the HTML input type date functionality.

Key combination	Effect
Left Arrow	Move one character to the left
Right Arrow	Move one character to the left
Home	Move to the beginning
End	Move to the end
CTRL/COMMAND + Left Arrow	Move to the beginning of the date/time section - current one or left one
CTRL/COMMAND + Right Arrow	Move to the end of the date/time section - current on or right one
Down Arrow	On a date/time section should decrement that part of the edited date
Up Arrow	On a date/time section should increment that part of the edited date
CTRL+;	Sets the current date and time as the value of the editor

Note that in the igxMask directive similar navigation can happen using the CTRL + Arrow Left/Right keys and ALT + Arrow Left/Right keys (demo).

4. Test Scenarios

Format:

Input format:

Should correctly display input format during user input.
Should correctly format - Pasting/inserting not fully formatted dates.
input -"1/1/220 1:1:1:1" - input format/mask "_1/_1/_220 _1:_1:_1:__1" - display format "1/1/220 1:1:1:100"
input - 10/10/2020 10:10:10:111 - input format/mask - "10/10/2020 10:10:10:111" - display format "10/10/2020 10:10:10:111"

Display format:

Should apply the display format defined
Numeric - Y, YY, YYYY, M, MM, D, DD
Short month name – MMM / Jan
Full month name – MMMM / January
Short day name – DDD / Mon
Full day name – DDDD / Monday
Should corectly display input and display formats, when different ones are defined for the component.
inputFormat: "MM/dd/yyyy hh:mm:ss:fff", displayFormat: "M/d/yyyy h:m:s:fff"

Properties/attributes:

Should disable the input when disabled property is set.
Should set the input as readonly when readonly property is set.
Editor should not be editable when readonly or disabled.

Keyboard Navigation:

Alt+ArrowRight: starting from first period start position(first possible position in the mask) – carret should jump to the end of the same period upon Alt+ArrowRight.
Alt+ArrowLeft: starting from the last period’s end position, carret should jump to the start of the same period upon Alt+ArrowLeft..
Alt+ArrowRight OR Alt+ArrowLeft: From any other position than the first or last in the mask – the carret should go to ne next period and be at the same (start OR end) position at all time.

Value:

Min/Max Value specified [*1] – workflow1 – directly manage value
Should prevent user input if the input is outside min/max values defined.
Should set as input the min or max value instead. (property managed?)

Validation:

Min/Max Value specified [*1]- workflow2 – notify the user / input clipper feature
Should prevent user input if the input is outside min/max values defined.
Should NOT set min/max values defined.
Should notify user if the input is outside min/max values set.

Separator: