Date Picker Specification

Owned by

Team Name

Boris Penkov

Yoanna Ivanova

Requires approval from

Plamena Miteva | Date: 19 Feb 2021
Stefan Ivanov | Date: 17 Feb 2021

Signed off by

Radoslav Mirchev | Date: 12 Mar 2021
Damyan Petev | Date: 19 Feb 2021

Revision History

Version	Users	Date	Notes
2	Boris Penkov, Plamena Miteva, Yoanna Ivanova	Date 15 Feb 2021

1. Overview

IgxDatePicker - 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.

When 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. IgxDatePicker displays in a dropdown mode by default.

Also, the user experience includes a read-only input (in dialog mode) that holds a single date in the following format by default - MM/dd/yyyy. Clicking on the input will result in a dialog pop-up that will hold a calendar from which the end-user may select a value.

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

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

Objectives

Selecting a date from the calendar
Dropdown mode (by default) and dialog mode for the calendar
Typing, pasting, dragging, and dropping a date string (in a pre-defined format) into the editor (dropdown mode)
Model binding
Support for min and max value, custom validation with bound model
Customizable input mask and display format
Localization
Keyboard navigation in the editor with specified key combinations for expanding and collapsing of the calendar (dropdown mode) igxDateTimeEditor keyboard navigation
Keyboard navigation in the calendar igxCalendar keyboard navigation
Changing the orientation of the calendar's header (dialog mode only) - horizontal or vertical
Highlight of today's date, customizable week start, customizable previous' and next month's visible days, customizable amount of months' views, display week numbers
Customizable positioning and open/close animation of the calendar
Customizable action buttons
ARIA support

Changing the label, prefixes, suffixes, and hint

Setting the label:

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

The igxPrefix, igxSuffix and igxHint directives may be used to project elements before, after and under the input field.

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 which replaces the default toggle icon. Toggle can be marked as prefix or suffix.

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

Acceptance criteria

All user stories must be satisfied.

2. User Stories

Developer stories:

Story 1: As a developer, I want to be able to implement a shortcut for the current day.
Story 2: As a developer, I want to be able to show and hide leading and trailing days from the previous and the following month visually identifying them as such.
Story 3: As a developer, I want to be able to set the first day of the week (Sunday or Monday) and the date format based on their locale.
Story 4: As a developer, I want to be able to show or hide week numbers.
Story 5: As a developer, I want to have a mechanism for canceling the opening and closing of the date picker dropdown/dialog.
Story 6: As a developer, I want to have a default template that does not require any additional configuration.
Story 7: As a developer, I want to be able to bind ngModel to the date picker.
Story 8: As a developer, I want to be able to provide custom formatting functionality.
Story 9: As a developer, I want to be able to set a label in the editor.
Story 10: As a developer, I want to be able to set a placeholder in the editor.
Story 11: As a developer, I want to be able to change component mode (dialog or dropdown).
Story 12: As a developer, I want to be able to set the number of displayed months in the calendar.
Story 13: As a developer, I want to be able to customize the buttons.
Story 14: As a developer, I want to be able to customize the input group look.
Story 15: As a developer, I want to be able to set the localization to be controlled through its locale input.
Story 16: As a developer, I want to be able to change the header orientation to horizontal or vertical (dialog mode only).
Story 17: As a developer, I want to be able to customize the position and animation of the calendar.
Story 18: As a developer, I want to be able to set business, weekend, disabled, and special days.

End-user stories:

Story 1: As an end-user, I want to be able to visually identify what day it is today – a day of the week, date of the month, year.
Story 2: As an end-user, I want to be able to select a date from dropdown/dialog.
Story 3: As an end-user, I want to be able to visually differentiate the selected date.
Story 4: As an end-user, I want to be able to visually differentiate business, weekend, disabled, and special days.
Story 5: As an end-user, I want to be able to navigate to upcoming and past days, months, and years in different ways (scroll, swipe, arrows, keyboard). I want to be able to navigate the calendar with the keyboard.
Story 6: As an end-user, I want to be able to edit dates in the input (dropdown mode only).
Story 7: As an end-user, I want to be informed if the dates I've entered are valid and within range (if such is specified).
Story 8: As an end-user, I want to be able to see more than one displayed month in the calendar simultaneously.
Story 9: As an end-user, I want to be able to see the weeks' numbers.
Story 10: As an end-user, I want to be able to see the calendar in a format familiar to me, e.g. 1 Dec 2021, 1.12.2021, 12/1/2021.

3. Functionality

Date input or selection
- When IgxDatePicker is in a dropdown mode (default mode), the user can either type a date in the input field or select a date from its calendar that automatically fills in the input field with the corresponding value after which the dropdown is collapsed. In dialog mode, the input is read-only so the user can select a date from its calendar that will lead to closing the dialog automatically. The IgxDatePicker can display a TODAY button (by default) that selects today's date and a CANCEL button (by default) that closes in and keeps the current selection. Both buttons will result in hiding the dropdown and dialog when pressed.
Calendar
- Year/Month/Day navigation
- Today’s date highlight
- Leading/trailing month days (configurable)
- First day of the week (configurable)
- Week numbers
- Multi-month view mode
- Header (dialog mode only)
Custom date 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 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 that is outside of the specified range is written in the editable editor, the picker model (if bound), will become invalid after blurring (by default).

3.1. End-User Experience

A user can select a date from the calendar, be it in dropdown (default) or dialog mode. In dropdown mode, a user will be able to type, copy/paste, drag/drop values in the editor. The input field can be focused by either clicking on the textbox or the label. Opening of the dropdown is achieved through a key combination or by clicking on the toggle icon. In dialog mode the input will always be read-only and clicking anywhere on it will open the dialog. A calendar's header appears only in dialog mode displayed in a horizontal or vertical orientation.

Filled Input Dropdown/Dialog Mode

Focused Input in Editable Dropdown Mode

Dropdown Mode (default) with buttons

Dialog Mode (the header in horizontal orientation)

Dialog Mode (the header in vertical orientation)

Multi-view mode

3.2. Developer Experience

By default, the date picker will be in editable dropdown mode. Templating of icons, hint, etc. is achieved through content projection.

3.3. Globalization/Localization

locale property affecting display and calendar
Display format supports date pipe formats locale agnostics
Tooltips on built-in buttons localizable through resource strings

3.4. Keyboard Navigation

Keys	Description
`Space`	Opens the dropdown/dialog calendar and focuses it
`Alt` + `↓`	Opens the dropdown calendar and focuses it
`Esc`	Closes the dropdown/dialog and focuses the last focused input field
`Enter`	Closes the dropdown/dialog, selecting the focused date and moves the focus to the last focused input field
`Alt` + `↑`	Closes the dropdown/dialog and focuses the last focused input field

For keyboard navigation inside of an editable editor please refer to IgxDateTimeEditorDirective specification

Validation

The Date Picker integrates with Angular's Form Control allowing ngModel and formControlName directives to be applied on the component. Given that, when the underlying model becomes invalid the Date Picker will reflect that visually. This allows for any built-in (e.g. required) as well as custom validators applied to be reflected in the component state. The Date Picker also implements the Validator interface so the minValue and maxValue options will also affect the validity of the model (rather than just the editor).

3.5. API

Options

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

Methods

Name	Description	Return type
select	Accepts a Date object and selects the corresponding date from the calendar.	void
clear	Clears the editor's date.	void
open	Opens the calendar.	void
close	Closes the calendar.	void
toggle	Toggles the calendar between opened and closed states.	void
increment	Accepts a `DatePart` and increments it by one. If no value is provided, it defaults to the part at the position of the cursor.	void
decrement	Accepts a `DatePart` and decrements it by one. If no value is provided, it defaults to the part at the position of the cursor.	void

Events

Name	Description	Emitted with
opening	Fired when the calendar has started opening, cancelable.	IBaseCancelableBrowserEventArgs
opened	Fired after the calendar has opened.	IBaseEventArgs
closing	Fired when the calendar has started closing, cancelable.	IBaseCancelableBrowserEventArgs
closed	Fired after the calendar has closed.	IBaseEventArgs
valueChange	Emitted when the picker's value changes. Allows two-way binding of `value`.	Date
validationFailed	Emitted when a user enters an invalid date string or when the value is not within a min/max range.	IDatePickerValidationFailedEventArgs

API Reference:

4. Test Scenarios

Interaction

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

Rendering

Scenario 1: All input properties are initialized with their default values.
Scenario 2: Should be able to change the mode at runtime.
Scenario 3: Today's date is highlighted.
Scenario 4: Focusing in dropdown mode selects the text in the input.
Scenario 5: When disabled the disabled class is applied to the input.
Scenario 6: When in dialog mode a modal overlay with the calendar is shown/hidden on opening/closing.
Scenario 7: When in dropdown mode an overlay with dropdown is shown/hidden on opening/closing.
Scenario 8: When in dropdown mode the dropdown opens below the input by default if there is enough space and above otherwise.
Scenario 9: All ARIA attributes should be applied correctly.

API

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

5. Accessibility

ARIA Support

The IgxDatePickerComponent is decorated with the following properties:

Input ARIA

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 will have a title that is initially set to Choose Date, after selecting a date from the picker, it will change to Change Date, clearing the picker's value will revert the title back to its initial state
aria-required is true if the picker has been marked as required