Date 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">
</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 Changing the default icon

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

<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, 2)" igxSuffix>expand_more</igx-icon>
    <igx-icon (click)="picker.decrement(DatePart.Days, 2)" 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 isSpinLoop to false should stop looping the drop down over the min/max date value.
Setting isSpinLoop 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
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
Months are rendered correctly when displayMonthsCount is set

4.3 API tests

All ControlValueAccessor interface methods are correctly implemented
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
increment() and decrement() methods should change date parts correctly
The select() method selects a date from the calendar and fires selecting and selected events
Selecting an invalid date does not trigger selection events
Selecting event is cancelable
Opening and closing events are cancelable

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.
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
mode	InteractionMode	Sets whether `IgxDatePickerComponent` is in dialog or dropdown mode.
value	Date	The value of the editor.
displayFormat	string	The display value of the editor.
inputFormat	string	The format that the editor will use to display the date/time.
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`.
weekStart	number	Sets the start day of the week.
locale	string	Locale settings used in displayFormat
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 or ElementRef	The container used for the pop up element.
type	IgxInputGroupType	Determines how the picker will be styled.

6.2 Methods

Name	Type	Description
select	void	Accepts a Date object and selects the corresponding date from the calendar.
open	void	Opens the calendar.
close	void	Closes the calendar.
toggle	void	Toggles the calendar between opened and closed state.
increment	void	Increments a given `DatePart` by a given threshold.
decrement	void	Decrements a given `DatePart` by a given threshold.

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.

API Reference:

7. ARIA Support

The IgxDatePickerComponent is decorated with the following properties:

role is dialog (when in dialog mode) and combobox (when in dropdown mode)
aria-haspopup is grid
aria-expanded - which shows if the calendar container is visible
aria-labelledby - which relates to a specified label
autocomplete is off to prevent the browser from remembering previous inputs
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