Date Range Picker Specification

Revision History

Version	User	Date	Notes

Konstantin Dinev | Date:
Radoslav Mirchev | Date:
Stefan Ivanov | Date:

1. Objectives

Provide an Angular native date picker widget that uses the igx-calendar and lets users input or select a date value. The display and input formats are customizable.

If the input field is editable, the user can type a date or select one from the calendar that appears in a dropdown below the input field.

Here is the basic definition of an igx-date-picker:

<igx-date-picker [(ngModel)]="date">
    <label igxLabel>Date</label>
</igx-date-picker>

The default user experience includes a readonly input that holds a single date in the following format - MM/dd/yyyy. Clicking on the input will result in a dialog pop-up that will hold a calendar from which an end user may select a value.

2. Features

Selecting a date from the calendar.
Dropdown and dialog modes for the calendar.
Typing, pasting, dragging and dropping a date string (in a pre-defined format) into the editor with an immediate effect in the calendar.
Support for min and max dates.
Model binding and custom validation.
Customizable formats for the mask in and outside of edit mode.
Keyboard navigation in the editor with specified key combinations for expanding and collapsing of the calendar (dropdown mode).
Keyboard navigation in the calendar.
Highlight of today's date, customizable week start, customizable previous' and next month's visible days, customizable amount of months' views, week numbers.
Customizable positioning and open/close animation of the calendar.
Expanding/collapsing of the picker's calendar upon events.
ARIA support

2.1 Changing the label

<igx-date-picker>
    <label igxLabel>Custom Label</label>
</igx-date-picker>

2.2 Setting prefixes and suffixes

The igxPrefix and igxSuffix directives may be used to determine where the templated element will be placed.

Here is an example with the igx-icon:

<igx-date-picker #picker>
    <igx-icon igxSuffix (click)="picker.open()">
        calendar_view_day
    </igx-icon>
</igx-date-picker>

You can add multiple instances of the igxPrefix and igxSuffix directives which will stack one after the other. For example these could be used to provide the end user with the ability to spin a date portion with two buttons. Also, having projected icons like this will not affect the default toggle icon.

<igx-date-picker #picker>
    <igx-icon (click)="picker.increment(DatePart.Days)" igxSuffix>expand_more</igx-icon>
    <igx-icon (click)="picker.decrement(DatePart.Days)" igxSuffix>expand_less</igx-icon>
</igx-date-picker>

Additionally, the IgxPickerToggleComponent can be used as wrapper around a projected element. This adds a default click handler to it. It should also be mentioned that this acts as an override to the default toggle icon and as such it can not be stacked.

<igx-date-picker>
    <igx-picker-toggle igxPrefix>
       <igx-icon>calendar_view_day</igx-icon>
    </igx-picker-toggle>
</igx-date-picker>

3. User Scenarios

3.1 As an end user

P0

Story 1: I want to be able to visually identify what day it is today – day of the week, date of the month.
Story 2: I want to be able to visually differentiate the selected date.
Story 3: I want to be able to visually differentiate business, weekend and disabled days.
Story 4: I want to be able to navigate to upcoming and past months and years in different ways. (scroll, swipe, arrows, keyboard)
Story 5: I want to be able to navigate the calendar with the keyboard.
Story 6: I want to be able to edit dates in the editor (dropdown mode).
Story 7: I want to be informed if the dates I've entered are valid and within range (if such is specified).

3.2 As a developer

P0

Story 1: I want to be able to implement a shortcut for the current day.
Story 2: I want be able to show and hide leading and trailing days from the previous and the following month visually identifying them as such.
Story 3: I want to be able to set the starting/first day of the week and the date format based on their locale.
Story 4: I want to have a mechanism for canceling the closing of the date picker dropdown/dialog.
Story 5: I want to have a default template which does not require any additional configuration.
Story 6: I want to be able to bind ngModel to the date picker.
Story 7: I want to be able to provide custom formatting functionality.
Story 8: I want to be able to set a label in the editor.
Story 9: I want to be able to set a placeholder in the editor.

3.3 Acceptance criteria

All user stories must be satisfied.

4. Test Scenarios

4.1 Interaction tests

Toggle icon should open/close the dropdown and keep current selection.
Alt + ArrowDown/ArrowUp keys should open/close the dropdown.
Space key opens the dropdown; Enter key closes it and the input accepts current selection.
Escape key closes the dropdown discarding the selected date in the calendar.
Selecting a date from the dropdown closes the calendar and the input accepts current selection.
Clear button should reset the date value.
User is able to navigate through date parts using the arrow keys.
User is able to navigate through date parts using the mouse wheel.
Setting spinLoop to false should stop looping the drop down over the min/max date value.
Setting spinLoop to false should not accept values from the drop down before/over the min/max values when they are set.
Changing a date part should not affect hours, minutes, seconds and milliseconds of the selected date.

4.2 Rendering tests

All input properties are initialized with their default values.
Should be able to change the mode at runtime.
Today's date is highlighted.
Focusing in dropdown mode selects the text in the input.
When disabled the disabled class is applied to the input.
When in dialog mode a modal overlay with calendar is shown/hidden on opening/closing.
When in dropdown mode an overlay with dropdown is shown/hidden on opening/closing.
When in dropdown mode the dropdown opens below the input by default if there is enough space and above otherwise.
All aria attributes should be applied correctly.
Applies an input format on the editor as per the displayFormat property if it contains only numeric date/time parts and inputFormat is not set.
Resolves to the default locale-based input format for the editor(s) in case inputFormat or displayFromat are not set.

4.3 API tests

The picker should update its value properly when bound with ngModel
The open() method opens the dropdown and triggers opening and opened events.
The close() method closes the dropdown and triggers closing and closed events.
The toggle() method toggles the calendar and triggers opening and closing events.
The select() method selects a date from the calendar and fires selecting and selected events.
The deselect() method removes selection from the calendar.
The clear() method sets the value to null, emits valueChange and sets the value to null.
the selectToday() method selects the current day from the calendar.
the increment() method increments a DatePart by one and valueChange is emitted.
the decrement() method decrements a DatePart by one and valueChange is emitted.
Entering an invalid date does not trigger selection events but triggers.
Entering an invalid date or selecting a date outside of a specified min/max range triggers validationFailed.
Selecting event is cancelable.
Opening and closing events are cancelable.
If set, minValue and maxValue should determine the picker's valid state.

5. Functionality

Date input or selection
- If the picker is in a dropdown mode, selecting a date from its calendar will automatically fill in the input field with the corresponding value after which the dropdown is collapsed. If the picker is in a dialog mode, the user will have to press confirmation button (by default OK) which will then fill in the value in the editor. Pressing the CANCEL (by default) button will revert any selection made. Both of these buttons will result in the dialog hiding when pressed.
Calendar
- Year/Month/Day navigation
- Today’s Date Highlight
- leading/trailing month days (configurable)
- First day of the week configuration support
Custom date display format
- The IgxDatePicker makes use of IgxDateTimeEditor which allows passing in of display format based on Angular DatePipe's standards.
- Custom formatting can be applied using the inputFormat property.
- 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.
Date Validation (min/max check)
- Min and max values can be set which can additionally configure the validity of the picker. Additionally, the calendar will display all dates that are outside of the min-max range as grayed out and they will not be selectable from its UI. If a date which is outside of the specified range is written in the editable editor, the picker will become invalid after blurring (by default).

5.1 Developer Experience

By default the date picker will be in a dialog state with a readonly input. Templating of icons and placeholders is achieved through content projection.

5.2 End user Experience

A user can select a date from the calendar, be it in dropdown or dialog mode. In dialog mode the input will always be readonly and clicking anywhere on it will open the dialog. In dropdown mode a user will be able to type, copy/paste, drag/drop values in the editor. Opening of the dropdown menu is achieved through a key combination or by clicking on the toggle icon.

5.3 Keyboard Navigation

Alt + Down Arrow - Opens the drop-down calendar and focuses it
Alt + Up Arrow - Closes the drop-down and focuses the last focused input field
Esc - Closes the drop-down and focuses the last focused input field
For keyboard navigation inside of an editable editor please refer to IgxDateTimeEditorDirective specification

Name	Type	Description
id	string	`attr.id` of the picker.
mode	InteractionMode	Sets whether `IgxDatePickerComponent` is in dialog or dropdown mode.
value	Date	The value of the editor.
minValue	Date \| string	The minimum value required for the picker to remain valid.
maxValue	Date \| string	The maximum value required for the editor to remain valid.
displayFormat	string	The display value of the editor.
inputFormat	string	The format that the editor will use to display the date/time.
formatOptions	IFormatOptions	The calendar's format options for the day view.
specialDates	DateRangeDescriptor[]	Dates that will be marked as special in the calendar.
disabledDates	DateRangeDescriptor[]	Dates that will be disabled in the calendar.
formatViews	IFormatViews	Determines if `day`, `month` and `year` will be rendered in the calendar. `locale` and `formatOptions` are taken into account as well, if present.
displayMonthsCount	number	Sets the number of displayed month views. Default is `2`.
hideOutsideDays	boolean	Sets whether dates that are not part of the current month will be displayed. Default is `false`.
showWeekNumbers	number	Shows or hides week numbers.
tabindex	number	The editor's tabindex
weekStart	number	Sets the start day of the week. If `weekStart` is not explicitly set, its value to be determined based on the calendar `locale` value, using `getLocaleFirstDayOfWeek`
locale	string	Locale settings used in displayFormat. If this `locale` is not set, its value to be determined based on the global Angular application `LOCALE_ID`.
overlaySettings	OverlaySettings	Changes the default overlay settings used by the `IgxDatePickerComponent`.
placeholder	string	Sets the placeholder text for an empty input.
disabled	boolean	Disables or enables the picker.
outlet	IgxOverlayOutletDirective \| ElementRef	The container used for the pop up element.
type	IgxInputGroupType	Determines how the picker will be styled.
spinLoop	boolean	Determines if the currently spun date segment should loop over.
cancelButtonLabel	string	The label of the `cancel` button. No button is rendered if there is no label provided.
todayButtonLabel	string	The label of the `select today` button. No button is rendered if there is no label provided.
dialogHeader	DialogHeader	Determines whether the calendar's header renders in `vertical` or `horizontal` state. Applies only in `dialog` mode.

6.2 Methods

Name	Type	Description
select	void	Accepts a Date object and selects the corresponding date from the calendar.
deselect	void	Deselects the calendar's date.
selectToday	void	Selects today in the calendar.
clear	void	Clears the picker's input.
open	void	Opens the calendar.
close	void	Closes the calendar.
toggle	void	Toggles the calendar between opened and closed state.
increment	void	Accepts a `DatePart` and increments it by one. If no value is provided, it defaults to the part at the position of the cursor.
decrement	void	Accepts a `DatePart` and decrements it by one. If no value is provided, it defaults to the part at the position of the cursor.

6.3 Events

Name	Emitted with	Description
selecting	IBaseCancelableBrowserEventArgs	Fired before the picker finishes a selection, cancelable.
selected	Date	Fired when the selected date value has changed.
opening	IBaseCancelableBrowserEventArgs	Fired when the calendar has started opening, cancelable.
opened	IBaseEventArgs	Fired after the calendar has opened.
closing	IBaseCancelableBrowserEventArgs	Fired when the calendar has started closing, cancelable.
closed	IBaseEventArgs	Fired after the calendar has closed.
valueChange	Date	Emitted when the picker's value changes.
validationFailed	IDatePickerValidationFailedEventArgs	Emitted when the picker enters an invalid state.

API Reference:

7. ARIA Support

The IgxDatePickerComponent is decorated with the following properties:

role is combobox
aria-haspopup is dialog
aria-expanded - which shows if the calendar container is visible
aria-labelledby - which relates to a specified label
aria-autocomplete is off to prevent the browser from remembering previous inputs (when editable)
the default toggle icon has two variants for aria-label:
- in dialog mode it has a prompt text such as Choose Date if there is no selected date; selecting any date from the calendar will change that to Change Date as well as the currently chosen date which is in the picker's specified format
- in dropdown mode it holds the Choose Date prompt and after selecting a date from the calendar will change to Change Date; it should also be excluded from the TAB sequence
aria-required is true if the picker has been marked as required