Date Picker Specification

Owned by

Team Name

Boris Penkov

Yoanna Ivanova

Requires approval from

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

Signed off by

Radoslav Mirchev | Date:
Damyan Petev | Date:

Revision History

Version	Users	Date	Notes
1	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 and custom validation with bound model
Support for min and max value
Customizable formats for the mask in and outside of edit mode
Localization and custom date formatting support
Keyboard navigation in the editor with specified key combinations for expanding and collapsing of the calendar (dropdown mode)
Changing the orientation of the calendar's header (dialog mode only) - horizontal or vertical
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, display week numbers
Customizable positioning and open/close animation of the calendar
Customizable action buttons
ARIA support

Changing the label

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

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 which 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 cannot be stacked.

<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 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.
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 implement keyboard navigation.

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).
Story 6: As an end-user, I want to be able to navigate the calendar with the keyboard.
Story 7: As an end-user, I want to be able to edit dates in the input (dropdown mode only).
Story 8: 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 9: As an end-user, I want to be able to see more than one displayed month in the calendar simultaneously.
Story 10: As an end-user, I want to be able to see the weeks' numbers.
Story 11: 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-view mode
- Header (dialog mode only)
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 that is outside of the specified range is written in the editable editor, the picker 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. 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 Dialog Mode (In Dropdown Mode a clear icon will also appear)

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 and placeholders is achieved through content projection.

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

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
`←`	In dropdown mode moves the caret one character to the left where possible
`→`	In dropdown mode moves the caret one character to the right where possible
`↑`	In dropdown mode increments the date portion where the caret currently is
`↓`	In dropdown mode decrements the date portion where the caret currently is

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

Validation

Validation should work as expected in both scenarios - dropdown mode with an editable input and dialog mode with a read-only input.

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
formatOptions	The calendar's format options for the day view.	IFormatOptions
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.	IFormatViews
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.	number
locale	Locale settings used in displayFormat.	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
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.	HeaderOrientation

Methods

Name	Description	Return type
select	Accepts a Date object and selects the corresponding date from the calendar.	void
deselect	Deselects the calendar's date.	void
selectToday	Selects today in the calendar.	void
clear	Clears the picker's input.	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
selecting	Fired before the picker finishes a selection, cancelable.	IBaseCancelableBrowserEventArgs
selected	Fired when the selected date value has changed.	Date
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.	Date
validationFailed	Emitted when the picker enters an invalid state.	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 fires selecting and selected events.
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 selectToday() method selects the current day from the calendar.
Scenario 9: the increment() method increments a DatePart by one and valueChange is emitted.
Scenario 10: the decrement() method decrements a DatePart by one and valueChange is emitted.
Scenario 11: Entering an invalid date does not trigger selection events but triggers.
Scenario 12: Entering an invalid date or selecting a date outside of a specified min/max range triggers validationFailed.
Scenario 13: Selecting event is cancelable.
Scenario 14: Opening and closing events are cancelable.
Scenario 15: 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 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