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 format should be customizable but the date value is always in UTC ISO 8601 format.

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 igxPrefix (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.

<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 8: I want to be able to provide my own date editors and bind them to ngModel.
Story 9: I want to be able to provide custom formatting functionality.
Story 10: I want to be able to set a label in the editor.
Story 12: 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 General tests

User can change component's id
User can toggle the label visibility
User can change the default label
User can change the input tab index
User can get input edit element
User can change display format's locale
User is able to set custom formatting
User can change the calendar's start day of the week
Changing a date part should not affect hours, minutes, seconds and milliseconds of the selected date
Year can be changed from the calendar
Month can be changed from the calendar
An overlay is shown on date picker opening and hidden on component's closing
onOpened/onClosed event is fired on the picker's calendar expanding/collapsing
onSelection and valueChange events are emitted on date selection
deselectDate() method clears the component's value and emits valueChange event

4.2 Rendering tests

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

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	DateRange	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 `IgxDateRangeComponent`.
placeholder	string	Sets the placeholder text for an empty input.
disabled	boolean	Disables or enables the picker.
outlet	IgxOverlayOutletDirective	ElementRef
type	IgxInputGroupType	Determines how the picker will be styled.

6.2 Methods

Name	Type	Description
selectDate	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
dateSelected	Date	Fired when the selected date value has changed.
onOpening	IBaseCancelableBrowserEventArgs	Fired when the calendar has started opening.
onOpened	IBaseEventArgs	Fired after the calendar has opened.
onClosing	IBaseCancelableBrowserEventArgs	Fired when the calendar has started closing.
onClosed	IBaseEventArgs	Fired after the calendar has closed.