DateTime 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	Boris Penkov	January 31, 2020	Arranging stories
1.0	Boris Penkov	February 14, 2020	Update tests
1.1	January **, 2020	Februrary ** 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

P0

Story 1: I want to be able to display date/time values based on a defined input format.
Story 2: I want to be able to edit the date/time value in the editor.
Story 3: While editing I want the fields that need to be filled to be clearly indicated with prompt characters.
Story 4: As an end-user I expect to see a placeholder text when the input is empty that suggests me what to type in.
Story 5: I want the editor to complete partially entered dates.
- _ _ _ _-12-_ _ > 2000-12-01
- 2012-_ _-_ _ > 2012-01-01
- 0015-_ _-_ _ > 1915-01-01 ? 2015-01-01
Story 6: I want the editor to clear any invalid input (on blur).
Story 7: Typing correction on user input. E.g. Typing 777777 will end in _7/_7/7777.

P1

Story 8: I want the editor to ignore/adjust any invalid value that I paste. "30/30/3333"
Story 9: I want the editor to handle entering partial dates or dates in short date format (century threshold).
Story 10: I want the editor to modify the date that the end user sees based on its UTC value and potentially specified time offset.
Story 11: I want the editor to have visual buttons that can be used to increment/decrement the editor's currently selected portion. (app scenario / input group integration?)
Story 12: I want to clear the entered value in the input using a clear button. (app scenario?)
Story 13: I want to have a visual cue about the portion of the time that is currently in focus / hovered through a subtle background / text coloring. (input group integration?)

As a developer

P0

Story 1: I want to define a mask specifying the date/time separate input format. mask (see Functionality, section Custom date display format)
Story 2: I want to define a mask specifying the date/time display format. format
Story 3: I want the editor to use the format as a placeholder when the option is not set.
Story 4: I want to be able to specify the prompt characters.
Story 5: I want to be able to set predefined masks in a simple manner - shortDate, longDate, etc like in DatePipe.
Story 6: Enumeration formats (shortDate, longDate) should be taken from locale settings.
Story 7: I want to be able to configure the editor as editable (default value), read-only and disabled.
Story 8: I want to be able to bind ngModel.
Story 9: I want to be able to set a default date/time value for the editor.
Story 10: 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.

P1

Story 11: I want to be able to instantiate the date/time editor directive on an input element inside IgxInputGroup.
Story 12 (optional) In addition or alternative to the custom format masks, I want to be able to enable/disable the zero prefixes for dates/months/hours e.g. 9:03 or 09:03.

Acceptance criteria

All user stories must be satisfied.

3. Functionality

Date input or selection
- property for input mask & display mask
Custom input format
- day - dd (21)
- month - MM (02, 12)
- year - yy (19); yyyy (2019)
- hours - hh (01, 12); HH (00, 23)
- minutes - mm (0, 60)
- seconds - ss (0, 60)
- AM/PM - tt
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

3.1 Validation

P0

Story 1: I want the editor accept Min and Max properties which control the validity of the ngModel.

P1

Story 2: I want to have validation on blur for date/time formats e.g. 30/02/2020 is not a valid date and on blur it will be changed to nearest valid calendar date 29/02/2020 or will revert to empty. Or will stay as it as now and form component will be marked as invalid.

Logged Issues

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

3.2 Keyboard Navigation

P0

Story 1: I expect to have keyboard navigation between date sections using Ctrl/Cmd + Arrow Left/Right.
- Jumps from current section to the same caret position of the next/previous section.
- On start/end sections, first jumps to the other end of the section following the direction of the arrow (RTL?)
Story 2: I expect to be able to increment/decrement date portions using Arrow Up/Down.
Story 3: I want to 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. (isSpinLoop?)
Story 4: I want to set the current day and time in the editor via a shortcut (Ctrl/Cmd + ; as it is in Excel).

P1

Story 5: I want to be able to specify the step (spin delta) at which the selected time part will be incremented / decremented. (one delta, or delta per section?)

Note

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

Incrementing/decrementing the date/time section where the cursor currently is via the keyboard:

Keyboard Navigation Table

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/COMMAND + ;	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. API

4.1 Options

Name	Type	Description
value	Date	The value of the editor.
mask	string	The display value of the editor.
format	string	The format that the editor will use to display the date/time.
minValue	string / Date	The maximum possible value that the editor will display.
maxValue	string / Date	The minimum possible value that the editor will display.
isSpinLoop	boolean	Loop over the currently spun segment.

4.2 Methods

Name	Type	Description
clear	void	Clears the input element of user input.
increment	void	Increments the current date/time portion.
decrement	void	Decrements the current date/time portion.

4.3 Events

Name	Type	Description
valueChanged	custom	Fired when the editor's value has changed.
validationFailed	custom	Fired when the editor is not within a specified range.

5. Test scenarios

Format:

Input format:

Should correctly display input format during user input
Should correctly 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
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"
Should display Default "/" separator if none is set
Should preserve the separator on paste/drag with other separator

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 display the Custom separator if such is defined

Properties/attributes:

Should disable the input when disabled property is set
Should set the input as readonly when readonly property is set
(API?) Editor should not be editable when readonly or disabled
if isSpinLoop is true (default), should spin around the date portion
if isSpinLoop is false, should not spin around the date portion
Min/Max should not block the user from entering dates outside of Min/Max range

Keyboard Navigation:

Ctrl+ArrowRight: starting from first period start position (first possible position in the mask) – caret should jump to the end of the same period upon Ctrl+ArrowRight
Ctrl+ArrowLeft: starting from the last period’s end position, caret should jump to the start of the same period upon Alt+ArrowLeft
Ctrl+ArrowRight OR Ctrl+ArrowLeft: From any other position than the first or last in the mask – the caret should go to ne next period and be at the same (start OR end) position at all time
Should be able to spin UP/DOWN the date portions

Value: