Skip to content

DateTime Editor Specification

Bozhidara Pachilova edited this page Oct 16, 2024 · 48 revisions

DateTime Editor Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility
  6. Assumptions and Limitations
  7. References

Owned by

Team Name

Developer Name

Yoanna Ivanova

Requires approval from

  • Peer Developer Name | Date:
  • Stefan Ivanov | Date: 17 Feb 2021

Signed off by

  • Radoslav Mirchev | Date:
  • Platform Architect Name | Date:

Revision History

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
1.3 Bozhidara Pachilova April 12, 2024 Update Custom input formats
1.4 Bozhidara Pachilova October 16, 2024 Add defaultFormatType property
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.

Objectives

  • 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

Acceptance criteria

All user stories must be satisfied.

Developer stories:

P0

  • Story 1: As a developer, I want to define a mask specifying the date/time separate inputFormat (see Functionality, section Custom date display format).
  • Story 2: As a developer, I want to define a mask specifying the date/time 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 the user 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: 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 12: As a developer, I expect the editor to complete partially entered dates.
    • _ _ _ _-12-_ _ > 2000-12-01
    • 2012-_ _-_ _ > 2012-01-01
    • 0015-_ _-_ _ > 2015-01-01
  • Story 13: As a developer, I expect that the editor will clear invalid input on blur.
  • Story 14: I want the editor accept Min and Max properties which control the validity of the ngModel.

P1

  • Story 15: As a developer, I want to be able to instantiate the date/time editor directive on an input element inside IgxInputGroup.
  • Story 16: As a developer, I want to be able to enable/disable the zero prefixes for dates/months/hours e.g. 9:03 or 09:03 in addition or alternative to the custom format masks.
  • Story 17: I want to be able to specify the step (spin delta) at which the selected time part will be incremented/decremented.
  • Story 18: As a developer, I expect typing correction on user input. For e.g. Typing 777777 will result in _7/_7/7777.
  • Story 19: As a developer, I want the editor to ignore/adjust any invalid value that the user pastes. "30/30/3333".\
  • Story 20: As a developer, I want to define a century threshold, e.g. if set to 30 it will convert 25 to 2025 and 35 to 1935.
  • Story 21: As a developer, I want the editor to modify the date that the end-user sees based on its UTC value and potentially specified time offset.
  • Story 22: As a developer, 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.

End-user stories:

P0

  • 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, I want to be able to paste or drag-and-drop dates from elsewhere into the editor.
  • Story 4: As an end-user, I want the fields that need to be filled to be clearly indicated with prompt characters while editing.
  • Story 5: 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 6: As an end-user, I expect to be guided and my input to be converted to a valid date and time as I type in the editor.
  • Story 7: As an end-user, I want to be notified if the date I inserted is not valid, e.g. does not fit in the allowed range or for another reason.

P1

  • Story 8: As an end-user, I want the editor to handle partial dates or dates in short date format.
  • Story 9: As an end-user, I want the editor to have buttons for incrementing/decrementing the currently selected date/time portion. (app scenario / input group integration?)
  • Story 10: As an end-user, I want to clear the entered value in the input using a clear button.
  • Story 11: 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 12: As an end-user, I want 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.
  • Date/Time input or selection
    • Property for input mask & display mask
  • Custom input format
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.
s Seconds, will be coerced with a leading zero while editing.
ss Seconds with an explicitly set leading zero.
S Fractional seconds 1 digit, will be coerced with leading zero while editing.
SS Fractional seconds 2 digits, will be coerced with leading zero while editing.
SSS Fractional seconds 3 digits with explicitly set leading zero.
tt AM/PM section for 12-hour format.
a AM/PM section for 12-hour format.
aa AM/PM section for 12-hour format.
aaa AM/PM section for 12-hour format.
aaaa AM/PM section for 12-hour format.
aaaaa a/p section for 12-hour format.
  • Custom date/time display format
    • The IgxDateTimeEditor uses Angular's DatePipe which allows it to support pre-defined format options, such as shortDate and longDate. It can also accept a constructed format string using characters supported by DatePipe, e.g. EE/MM/yyyy.
  • In case the inputFormat property is not set, the applied input format of the underlying editor is inferred from displayFormat, if set and if it contains only numeric date-time parts.

3.1. End-User Experience

Date/Time Editor

Focused Date/Time Editor

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

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: 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:

Note: In the igxMask directive similar navigation can happen using the CTRL + Arrow Left/Right keys and ALT + Arrow Left/Right keys (demo).
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.5. API

Options

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
defaultFormatType Defines the date parts for editing in the default format. 'date' | 'time' | 'dateTime'

Methods

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

Events

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
  • 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
  • Scenario 2: Should apply an input format as per the displayFormat property if it contains only numeric date/time parts and inputFormat is not set.
  • Scenario 3: Should resolve to the default locale-based input format for the editor in case inputFormat or displayFromat are not set.
  • Scenario 4: Should set the default input format as per the defaultFormatType property and according to the locale.

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

sample-design

Clone this wiki locally