-
Notifications
You must be signed in to change notification settings - Fork 162
DateTime Editor Specification
- Overview
- User Stories
- Functionality
- Test Scenarios
- Accessibility
- Assumptions and Limitations
- References
Team Name
Developer Name
Yoanna Ivanova
- Peer Developer Name | Date:
- Stefan Ivanov | Date: 17 Feb 2021
- Radoslav Mirchev | Date:
- Platform Architect Name | Date:
Version | Users | 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 | Boris Penkov | March 23, 2020 | API; User and Developer Stories |
1.2 | Boris Penkov | March 30, 2020 | Update API |
GitHub | Milestone | Issue# | Name |
---|---|---|---|
igniteui-angular | #6271 | Separate date and time editing functionalities from igxDatePicker and igxTimePicker into a new directive |
igxDateTimeEditor
lets users 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.
- Model binding and custom validation
- Keyboard navigation with specified key combinations between date/time sections, increment and decrement date/time portions, setting the current day/time
- Support for different display and input formats
- Support for min and max value
All user stories must be satisfied.
Developer stories:
- Story 1: As a developer, I want to define a mask specifying the date/time separate input format.
inputFormat
(seeFunctionality
, sectionCustom date display format
) - Story 2: As a developer, I want to define a mask specifying the date/time display format.
displayFormat
- Story 3: As a developer, I want the editor to use the format as a placeholder when the option is not set.
- Story 4: As a developer, I want to be able to specify the prompt characters.
- Story 5: As a developer, I want to be able to set predefined masks in a simple manner -
shortDate, longDate, etc
like in DatePipe. - Story 6: As a developer, I want enumeration formats (
shortDate, longDate
) to be taken from locale settings. - Story 7: As a developer, I want to be able to configure the editor as editable (default value), read-only and disabled.
- Story 8: As a developer, I want to be able to bind
ngModel
. - Story 9: As a developer, I want to be able to set a default date/time value for the editor.
- Story 10: As a developer, 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 11: As a developer, I want to be able to instantiate the date/time editor directive on an input element inside
IgxInputGroup
. - Story 12 (optional): As a developer, I want to be able to enable/disable the zero prefixes for dates/months/hours e.g.
9:03
or09:03
in addition or alternative to the custom format masks.
End-user stories:
- Story 1: As an end-user, I want to be able to display date/time values based on a defined input format.
- Story 2: As an end-user, I want to be able to edit the date/time value in the editor.
- Story 3: As an end-user, 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 to me what to type in.
- Story 5: As an end-user, I want the editor to complete partially entered dates.
-
_ _ _ _-12-_ _
>2000-12-01
-
2012-_ _-_ _
>2012-01-01
-
0015-_ _-_ _
>2015-01-01
-
- Story 6: As an end-user, I want the editor to clear any invalid input (on blur).
- Story 7: As an end-user, I want to have typing correction on user input. For e.g. Typing 777777 will result in _7/_7/7777.
- Story 8: As an end-user, I want the editor to ignore/adjust any invalid value that I paste. "30/30/3333"
- Story 9: As an end-user, I want the editor to handle entering partial dates or dates in short date format (century threshold).
- Story 10: As an end-user, 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: As an end-user, 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: As an end-user, I want to clear the entered value in the input using a
clear
button. (app scenario?) - Story 13: As an end-user, 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?)
- Story 14: As an end-user, I want to be able to use the mouse wheel to spin date/time portions. The spinning should occur on the current cursor position.
- Date/Time 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
- day -
- Custom date/time display format
- The
IgxDateTimeEditor
uses Angular's DatePipe which allows it to support pre-defined format options, such asshortDate
andlongDate
. It can also accept a constructed format string using characters supported byDatePipe
, e.g.EE/MM/yyyy
.
- The
3.1. End-User Experience
** Integration scenarios or functionality with other features/components prototype ** End-to-end user experienceprototype ** Prepared design files for styling e.g. interplay with features and light/dark variants design hand-off
3.2. Developer Experience
3.3. Globalization/Localization
Describe any special localization requirements such as the number of localizable strings, regional formats
3.4. Keyboard Navigation
- Story 1: I expect to have keyboard navigation between date sections using Ctrl/Cmd + Arrow Left/Right.
- Jumps from the 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.
- Story 4: I want to set the current day and time in the editor via a shortcut (Ctrl/Cmd + ; as it is in Excel).
- 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:
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 |
Note: In the igxMask directive similar navigation can happen using the CTRL + Arrow Left/Right keys and ALT + Arrow Left/Right keys (demo).
- Story 1: I want the editor accept Min and Max properties which control the validity of the
ngModel
.
- 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 date29/02/2020
or will revert to empty. Or will stay as it as now and form component will be marked as invalid.
- 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.5. API
Name | Description | Type |
---|---|---|
value | The value of the editor. | Date |
displayFormat | The display value of the editor. | string |
inputFormat | The format that the editor will use to display the date/time. | string |
minValue | Sets the minimum value required for the editor to remain valid. | string / Date |
maxValue | Sets the maximum value required for the editor to remain valid. | string / Date |
isSpinLoop | Loop over the currently spun segment. | boolean |
promptChar | Defines the empty characters in the mask. | string |
locale | Locale settings used in displayFormat. | string |
Name | Description | Return type |
---|---|---|
clear | Clears the input element of user input. | void |
increment | Increments the current date/time portion. | void |
decrement | Decrements the current date/time portion. | void |
Name | Description | Type |
---|---|---|
valueChanged | Fired when the editor's value has changed. | custom |
validationFailed | Fired when the editor is not within a specified range. | custom |
Input format
- Scenario 1: Should correctly display input format during user input
- Scenario 2: Should correctly display input and display formats, when different ones are defined for the component
- inputFormat: "MM/dd/yyyy hh:mm:ss tt", displayFormat:
M/d/yyyy h:m:s tt
- inputFormat: "MM/dd/yyyy hh:mm:ss tt", displayFormat:
- Scenario 3: Should correctly format - Pasting/inserting not fully formatted dates
- input -"1/1/220 1:1:1" - input format/mask "_1/_1/_220 _1:_1:_1" - display format "1/1/220 1:1:1"
- input - 10/10/2020 10:10:10 - input format/mask - "10/10/2020 10:10:10" - display format "10/10/2020 10:10:10"
Display format
- Scenario 1: 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 – EEE / Mon
- Full day name – EEEE / Monday
Properties/attributes
- Scenario 1: Should disable the input when the disabled property is set
- Scenario 2: Should set the input as read-only when read-only property is set
- Scenario 3: (API?) Editor should not be editable when read-only or disabled
- Scenario 4: if isSpinLoop is true (default), should spin around the date portion
- Scenario 5: if isSpinLoop is false, should not spin around the date portion
- Scenario 6: Min/Max should not block the user from entering dates outside of Min/Max range
Keyboard Navigation
- Scenario 1: 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
- Scenario 2: Ctrl+ArrowLeft: starting from the last period’s end position, caret should jump to the start of the same period upon Alt+ArrowLeft
- Scenario 3: Ctrl+ArrowRight OR Ctrl+ArrowLeft: From any other position than the first or last in the mask – the caret should go to the next period and be at the same (start OR end) position at all time
- Scenario 4: Should be able to spin UP/DOWN the date portions
Value
- Scenario 1: Should autofill missing date/time segments on blur
- Scenario 2: Should correctly show year based on century threshold (P1)
- Scenario 3: Should spin/evaluate date input if an invalid date is pasted (P1)
Validation
- Scenario 1: Should NOT set min/max values defined
- Scenario 2: Should notify the user if the input is outside min/max values set
- Scenario 3: Should enter an invalid state if the input does not satisfy min/max props
- Scenario 4: Should not allow invalid dates to be entered (P1)
ARIA Support
Not applicable
RTL Support
Assumptions | Limitation Notes |
---|---|