Date Picker Specification

Revision History

Version	User	Date	Notes
0.1	St.Dimitrov	23.06.2017	initial draft
0.1	St.Bozalieva	23.06.2017
0.2	Svetla Boykova	13.11.2018	editing and dropdown support
0.2	Stefan Ivanov	22.11.2018
0.3	Stefan Ivanov	07.05.2019	adding dropdown buttons
0.4	Ivaylo Ganchev	09.12.2019	adding input focus details
0.5	Stefan Ivanov	21.01.2020	moving stories for the editor to its specification

Borislav Kulov | Date: 07.05.2019
Konstantin Dinev | Date:

1. Overview

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

Objectives

Provide an Angular native date picker widget that extends the igx-calendar and lets users input or select a date value. The display format could be customized but the date value is always in UTC ISO 8601 format.

If the input field is editable, the user can type date or select one from the calendar that appears in a dropdown below the input field.

2. User Scenarios

The date picker widgets supports the following use scenarios:

Highlight todays’ date
Allow fast navigating to the date today
Indicate selected date and have it displayed(in text/input)
Allow expand/collapse of the date picker calendar upon events (e.g., date pick)
Allow date setting programmatically
Allow only single date selection
Multiple months displayed
Vertical display
Calendar could displays 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 shows in header the selected day (only for single selection)
Calendar allows navigation to other months/years
Date display format is customizable
Display date is spin-able by a delta of 1. Upon selection of a day, month or year keys UP/DOWN and PageUP/PageDown allow incrementing/decrementing the selected date element
Input Field integration
Allow Hide/Show input label.
Allow customization of input label.
Change the default label by placing an igxlabel inside a tag nested in the component.

View shown as a drop down from a date picker input

Views with header for placing in the page content

As an end user

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 current day.
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 possible for the user to select a single, multiple days or range of days upon click/tap on dates.
Story 6: I want to either type in a date inside the input or select it from the dropdown when the date picker
Story 7: I want to be able to navigate the calendar with the keyboard

Story 8: I want to be able to close the date picker dropdown by discarding my current state upon clicking on the CLOSE button or outside of the drop-down (behavior is identical to hitting the ESC key).

Story 9: I want to be able to select the current date upon clicking on the TODAY button, which will also close the drop-down.

As a developer

Story 1: I want to be able to implement a date picker in my application.
Story 2: I want to specify whether the date picker is editable and shows a dropdown or read-only that prompts a modal dialog.
Story 3: I want to implement a shortcut for the current day.
Story 4: 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 5: I want to set the starting/first day of the week and the date format based on their locale.
Story 6: I want to have a min width for the dropdown when the date picker is editable so that is doesn't get squeezed and distorted if the input is too narrow
Story 7: I want to be able to customize the buttons in the date picker drop-down e.g. remove the CLOSE button or add a third one
Story 8: I want to have a mechanism for canceling the closing of the date picker dropdown

Acceptance criteria

All user stories must be satisfied.

Functionality

Date input or selection
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
- List of date pattern is used:
- Y: year field without century and without leading zero Sample display value: 9 for 2009-06-21
- YY: year field without century and with leading zero Sample display value: 09 for 2009-06-21
- YYYY: year field with leading zeros Sample display value: 2009 for 2009-06-21
- M: month field as digit without leading zero Sample display value: 7 for 2009-07-21
- MM: month field as digit with leading zero Sample display value: 07 for 2009-07-21
- MMM: month field as short month name (up to 4 letters) Sample display value: Aug for 2017-08-21
- Short month name Full month name
  
  Jan January
  
  Feb February
  
  Mar March
  
  Apr April
  
  May May
  
  Jun June
  
  Jul July
  
  Aug August
  
  Sept September
  
  Oct October
  
  Nov November
  
  Dec December
- MMMM: month field as long month name Sample display value: August for 2017-08-21
- D: day of month field without leading zero Sample display value: 5 for 2017-08-05
- DD: day of month field with leading zero Sample display value: 05 for 2017-08-05
- DDD: day of the week as short name Sample display value: Thu for 2017-06-22
- Short weekday name Full weekday name
  
  Mon Monday
  
  Tue Tuesday
  
  Wed Wednesday
  
  Thu Thursday
  
  Fri Friday
  
  Sat Saturday
  
  Sun Sunday
- DDDD: day of the week as long name Sample display value: Friday for 2017-06-23
Date Validation (min/max check) – min and max day are settable. Days before the min and after he max value could not be selected in the calendar. If manually inputted, the value is reverted to the set min/max.

3.1 Developer Experience

The develop will be able to specify if the date picker is editable or readonly.

3.2 End user Experience

If the date picker is editable, when the user clicks on the input - he will be able to type date. He can select a date from calendar if he clicks on the calendar icon on the right. He can also delete the text input value using clear button.

On user interaction with the calendar, the input should always be focused (with modal dialog or dropdown), except in case of dropdown with outside click, when the component shouldn't do anything. This will allow to click on another focusable element.

3.3 Keyboard Navigation

Alt + Down Arrow - Open the drop-down calendar and focus the calendar
Alt + Up Arrow - Close the drop-down and focus the input field
Esc - Close the drop-down and focus the input field
Down Arrow - In edit mode pressing down arrow should decrement the current part of the edited date but only if that part is numeric
Up Arrow - In edit mode pressing up arrow should increment the current part of the edited date but only if that part is numeric

4. ARIA Support

aria-labelledby property for the input field. This will ensure the users of assistive technologies will also know what component is used for, upon input focus.