Date Range Picker Specification

Range Date Picker Specification

Revision History

Version	User	Date	Notes

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

1. Overview

GitHub	Milestone	Issue#	Name
igniteui-angular		#390	DateRangePicker - new component - research

Objectives

Provide an Angular native range date picker widget that allows a user to select a range of date values. The IgxDateRange has a default template that allows a user to select the start and end of a range from the calendar that appears in a dialog or dropdown menu, the input field in this case is readonly. Additionally, start and end input fields can be projected by making use of IgxDateTimeEditorDirective which adds editing functionality in the editors.

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

<igx-date-range-picker [(ngModel)]="range">
</igx-date-range-picker>

DateRange is the value that contains startDate and endDate. This configuration will produce the default behavior shown above.

Without writing any additional code, one will get the following default experience:
Date range picker is shown in one input group

Here is how the dialog/drop-down looks like, it will contain a single confirmation button to close the dialog/drop-down, leaving the most recent range specified as selected. If the user clicks outside the dialog/drop-down, we mimic the same behavior as for clicking the button. Drop-down closing is also possible via the input calendar icon that serves to open the drop-down as well. Selecting a range should update the input group contents in real-time.

One can customize the date range picker to show as two separate inputs separated by a "to" label that is localized, additionally this label is templatable.

<igx-date-range>
    <igx-date-start>
        <input igxInput igxDateTimeEditor type="text" [(ngModel)]="startDate">
    </igx-date-start>
 
    <igx-date-end>
        <input igxInput igxDateTimeEditor type="text" [(ngModel)]="endDate">
    </igx-date-end>
</igx-date-range>

Date range picker is shown with two input groups connected via a label

2. Features

2.1 Change label

<igx-date-range [mode]="'dropdown'">
    <label igxLabel>Date</label>
</igx-date-range>

2.2 Change default icon

Change calendar icon, with 2 directives (igxDateRangePrefix, igxDateRangeSuffix). Defining either will remove the default icon:

<igx-date-range #range>
    <igx-icon *igxDateRangeSuffix>
        calendar_view_day
    </igx-icon>
</igx-date-range>

<igx-date-range>
    <igx-date-start>
        <igx-icon *igxDateRangeSuffixIcon>
            calendar_view_day
        </igx-icon>
        <input igxInput igxDateTimeEditor type="text" [(ngModel)]="startDate">
    </igx-date-start>
 
    <igx-date-end>
        <input igxInput igxDateTimeEditor type="text" [(ngModel)]="endDate">
    </igx-date-end>
</igx-date-range>

2.3 Additional prefixes and suffixes

Outside the start and end dates

You can add multiple instances of igx-prefix without *igxDateRangePrefixIcon and if you do they will stack after the default prefix. Respectively, you can add multiple instances of igx-suffix without *igxDateRangeSuffixIcon and they will stack at the end of the input field.

<igx-date-range #range>
    <igx-prefix>
        <igx-icon>
           calendar_view_day
        </igx-icon>
    </igx-prefix>
</igx-date-range>

If you want prefixes/suffixes to be inside the inputs you should define them in the corresponding input groups.

<igx-date-range>
    <igx-date-start>
        <igx-icon *igxDateRangePrefixIcon></igx-icon> <!-- remove default icon -->
        <input igxInput igxDateTimeEditor type="text" [(ngModel)]="startDate">
        <igx-suffix>
            <igx-icon>
                calendar_view_day
            </igx-icon>
        </igx-suffix>
    </igx-date-start>
 
    <igx-date-end>
        <input igxInput igxDateTimeEditor type="text" [(ngModel)]="endDate">
        <igx-suffix>
            <igx-icon>
                calendar_view_day
            </igx-icon>
        </igx-suffix>
    </igx-date-end>
</igx-date-range>

3. User Scenarios

The date range picker widgets support the following user scenarios:

Highlight today's date
Indicate selected date range and have it displayed (in text/input)
Allow expand/collapse of the picker's calendar upon events (e.g. range selected)
Allow date range to be set programmatically
Multiple months displayed (default 2)
Calendar can display leading and trailing days from the previous and the following month
Calendar supports first day of the week customization (e.g. Sunday or Monday)
Calendar allows navigation to other months/years
Date display format is customizable
Input format is customizable (when using IgxDateTimeEditorDirective)

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 range.
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 make it possible for the user to select a range of days upon click/tap on dates.
Story 6: I want to be able to navigate the calendar with the keyboard.
Story 7: I want to be able to edit dates in the editor (dropdown mode).
Story 8: I want to be informed if the dates I've entered are valid and within range.

3.2 As a developer

P0

Story 1: I want 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 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 range 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 range picker.
Story 7: I want to be able to project igx-suffix without any additional setup.
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 choose between 1 or 2 editors for IgxDateRange.
Story 10: I want to be able to provide custom formatting functionality.
Story 11: I want to be able to set a label in the editor/s.
Story 12: I want to be able to set a placeholder in the editor/s, e.g. Choose your dates.

3.3 Acceptance criteria

All user stories must be satisfied.

4. Functionality

Date input or selection
- Selecting the start of the range will fill in the corresponding input field, without affecting the end field. If start and end are selected, deselecting start will clear the end field as well, while deselecting end will only clear the end field. The inputs will be cleared if there is no selection in the calendar. Additionally, by default, a placeholder text will be present in the empty fields. This placeholder text will be one of two things - the specified by the user input format (if none is specified, it shows the default input format) or if the user provides a label, it uses it as a placeholder.
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
- IgxDateRange makes use of IgxDateTimeEditor which allows passing in of display format based on Angular DatePipe's standards.
- Custom formatting logic using the formatter input can also be applied.
Custom date input format
- Valid masks for the day part are: d and dd, for the month part - M and MM and for the year part - y, yy and yyyy.
Date Validation (min/max check) – min and max can be set.
- IgxDateRange will flip start and end dates in its input(s) to match the corresponding range in the calendar. This applies as soon as the calendar opens.

4.1 Developer Experience

The range date picker's default template will contain an input that is readonly and changing the selected range will be possible only via the calendar or API. If a user projects igx-date-start and igx-date-end they will be editable by default which will allow an end user to change the range selection through them as well.

4.2 End user Experience

The user can select a date range from the calendar after opening the dropdown/dialog by clicking anywhere on input - this applies for the default template. With projected inputs, by default the end user will be limited to the prefix icon on the igx-date-start component. In two-input mode, the user will be able to edit the values within the editors. The calendar will only display a range selection if the two input fields are filled in with valid dates. Additionally, the value of the control will remain unchanged (so will the inputs' values) when opening/closing the calendar or when blurring the inputs.

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

4.4 Validation

Validation should also work as expected for the two variants - one readonly input and two inputs, separated by a label.

Validation when default scenario is used

Validation for two input groups connected via a label

In two input mode, if ngModel is present on the IgxDateRangePickerComponent both input fields will be taken into account when determining the control's validity. Placing ngModel on the projected inputs instead, will result in them being validated separately.

5. API

5.1 Options

Name	Type	Description
mode	InteractionMode	Sets whether `IgxDateRangeComponent` is in dialog or dropdown mode.
value	DateRange	The value of the range editor.
displayFormat	string	The display value of the editor.
inputFormat	string	The format that the editor will use to display the date/time.
formatter	function	Applies a custom formatter function on the selected or passed in date. Accepts a parameter of type `DateRange` and returns a `string` - the formatted values.
monthsViewNumber	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`.

5.2 Methods

Name	Type	Description
selectRange	void	Accepts `DateRange` object and select that range
selectRange	void	Accepts `Date` (start date) and the amount of days to be selected
open	void	Opens the calendar
close	void	Closes the calendar
toggle	void	Toggles the calendar

5.3 Events

Name	Emitted with	Description
rangeSelected	DateRange	Fired when the range 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.

API Reference:

6. ARIA Support

In 2014 the W3C finalized their WAI-ARIA specification which defined how to design Web content and Web applications to be more accessible to users with disabilities. The IgxDateRange has been designed so that it follows these guidelines.

The IgxDateRange is decorated with

combobox role
aria-haspopup="grid" attribute to indicate that IgxDateRange can popup a calendar container to suggest date values.
aria-expanded attribute showing if calendar container is visible.
aria-labelledby attribute to indicate the related label.