igxCalendar Specification

Calendar Specification

Owned by

Team Name

Developer Name

Yoanna Ivanova

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date: 26 Aug 2020
Aleksandar Kamenov | Date: 31 Aug 2020

Signed off by

Product Owner: Radoslav Mirchev | Date: 31 Aug 2020
Platform Architect Name | Date:

Revision History

Version	Users	Date	Notes
0.1	Zdravko Kolev		Initial implementation of test scenarios
0.2	Zdravko Kolev	08/07/2018	Adding disabled dates test scenarios
0.3	Zdravko Kolev	10/09/2018	Update test scenarios for the new `deselectDate` method
0.4	Nadia Robakova	01/10/2018	Update test scenarios for the new `deselectDate` method for range selection
0.5	Zdravko Kolev	02/10/2018	Update test scenarios for the new `deselectDate` method for range selection
0.6	Hristo Anastasov	30/07/2019	Update the Objectives, User Stories, End Stories, Test Scenarios and API Inputs regarding multi view calendar
0.7	Hristo Anastasov	09/08/2019	Update User Stories and API Inputs regarding multi view calendar
0.8	Hristo Anastasov	09/08/2019	Update User Stories and API Inputs regarding multi view calendar
0.9	Hristo Anastasov	17/09/2019	Update test plan with concrete tests to be implemented
1.1	Hristo Anastasov	07/07/2020	Emit events for viewDate and activeView changes, make activeView an input..
2.0	Yoanna Ivanova	26/08/2020	Add stories and design for week number support
2.1	Aleksandar Kamenov	31/08/2020	Update Developer Stories and API Inputs regarding week numbers feature.
3.0	Zdravko Kolev	10/12/2020	Keyboard navigation section update.

1. Overview

igxCalendar component - Angular native calendar that lets users to select a date value in variety of different ways. Users can select a single date, multiple dates or pick a range of dates.

Objectives

Provide Ignite UI for Angular igx-calendar component that supports the following features:

display date information
select a single date
select multiple dates
select multiple days in more than one month
pick a range of dates
pick a range of dates spanning more than one month
display week numbers
provide localization capabilities
provide date formatting capabilities
format views
provide keyboard navigation

2. User Stories

Developer stories:

Story 1: As a developer, I want to implement a single selection capability, so that I give users the option to select a date for certain action.
Story 2: As a developer, I want to implement multiple date selection capability.
Story 3: As a developer, I want to implement a range date selection capability.
Story 4: As a developer, I want to implement a localization and formatting capability. Those will be controlled and customized through the following properties - locale, formatOptions, formatViews.
Story 5: As a developer, I want to implement a capability to add customized dates display that also will change the locale representation based on the user location.
Story 6: As a developer, I want to implement "disabled" dates capability, so that I give users the option to set the calendar to display all past dates or future dates as disabled. Create two inputs disabledDates and specialDates that will receive array of DateRangeDescriptors.
Story 7: As a developer, I want to implement keyboard navigation, so that I give users the ability to navigate to next and previous month, year, and day with the keyboard.
Story 8: As a developer, I want to configure the number of month views displayed, so that I give users the ability to select multiple or range dates in a single screen/operation.
Story 9: As a developer, I want to configure the step used to shift to next/previous months displayed.
Story 10: As a developer, I want to implement "hidden" dates capability, so that I give users the option to hide the dates that do not belong to the current month.
Story 11: As a developer, I want to be able to show/hide week numbers via boolean property type.

End-user stories:

Story 1: As an end-user, I want the calendar to be responsive, so that I can get calendar layout on:
- desktop environment
- tablet-size touch environment
- phone-size touch environment
Story 2: As an end-user, I want the calendar to be touch-friendly so that I can select and navigate to different dates and months on touch-only environment.
Story 3: As an end-user, I want the capability to select range of dates in order to define a multi-day selection.
Story 4: As an end-user, I want the calendar to have templating capabilities.

{{ parts.month.combined | titlecase }} {{parts.day.combined }} {{ parts.weekday.combined }} {{ parts.month.combined }} {{ parts.year.combined }}

Story 5: As an end-user, I want the calendar to control the locale used for formatting and displaying the dates in the calendar.

<igx-calendar [locale]=”locale” …>

Story 6: As an end-user, I want the calendar to controls the date-time components in formatted output.
Story 7: As an end-user, I want the calendar to have different calendar views.
Story 8: As an end-user, I want the calendar to have "disabled" dates, e.g. past-dates, single dates, holidays.
Story 9: As an end-user, I want to be able to keep track of the number of the weeks, visualized as a first column in the days-view display.

3. Functionality

3.1. End-User Experience

View week numbers in Calendar

Font color: grays.500
Background color: grays.200
Background roundness: 4px

3.2. Developer Experience

Week numbers in Calendar

The first week is determined according to the ISO 8601

3.3. Globalization/Localization

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

3.4. API

Inputs

Name	Type	Description
weekStart	Number or WEEKDAYS	Sets which day the week will start. If `weekStart` is not explicitly set, its value to be determined based on the calendar `locale` value, using `getLocaleFirstDayOfWeek`
locale	string	Sets the locale used for formatting and displaying the dates in the calendar. If the calendar `locale` value is not set, I want its value to be determined based on the Angular application global `LOCALE_ID`. For more information check out this page for valid formats
selection	string	Sets the type of selection in the calendar. Valid values are single (default), multi and range
viewDate	Date	Sets the year/month that will be presented in the default view when the calendar renders. By default it is the first day in the current year/month
value	Date or Date[]	Gets/Sets the current value of the calendar widget. Both multi-selection and range selection return an array of selected dates.
formatOptions	Object	The format options passed along with the locale property used for formatting the dates. Defaults are { day: 'numeric', month: 'short', weekday: 'short', year: 'numeric' }.
formatViews	Object	Controls whether the date components in the different calendar views should be formatted according to the provided locale and formatOptions. Defaults are { day: false, month: true, year: false }. Does not affect rendering in the header.
vertical	boolean	Controls the layout of the calendar component. When vertical is set to true the calendar header will be rendered to the side of the calendar body.
monthViewsNumber	number	Controls the number of month views displayed.
hideOutsideDays	boolean	Controls the visibility of the dates that do not belong to the current month.
activeView	CalendarView enum	Sets the active view (CalendarView enum value (DEFAULT, YEAR, DECADE)
showWeekNumber	boolean	Show/hide the week numbers in the days-view display

Outputs

Name	Arguments Type	Description
onSelection	Date or Date[]	Fired when selection is made in the calendar. The event contains the selected value(s) based on the type of selection the component is set to
onViewDateChanged	IViewDateChangeEventArgs	Fired after the viewDate is changed (e.g. the year/month that is presented in the default view is changed). The event contains the previous and the current values of the viewDate property.
onActiveViewChanged	CalendarView	Fired after the view is changed, emits an CalendarView enum value (DEFAULT, YEAR, DECADE )

Methods

Name	Arguments	Return Type	Description
selectDate	date: Date or Date[]	void	Change the calendar selection. Calling this method will emit the onSelection event.

Template Context

Name	Type	Description
date	Date	The date object in the context of the template.
full	string	The full date representation returned after applying the formatOptions.
monthView	function	A function which when called puts the calendar in month view.
yearView	function	A function which when called puts the calendar in year view.
era	object	The era date component (if applicable) formatted to the supplied locale.
year	object	The year date component (if applicable) formatted to the supplied locale.
month	object	The month date component (if applicable) formatted to the supplied locale.
day	object	The day date component (if applicable) formatted to the supplied locale.
weekday	object	The weekday date component (if applicable) formatted to the supplied locale.

4. Test Scenarios

Automation

1. Verify a proper calendar model:

Scenario 1: 2017 June with first day set to Sunday
Scenario 2: 2017 June with first day set to Sunday and extra week
Scenario 3: 2017 June with first day set to Friday
Scenario 4: Leap year tests

2. Verify correct using of utility functions - leap year, monthRange, calendar timedelta, year timedelta, quarter timedelta, month timedelta, week timedelta, day timedelta, day timedelta, hour timedelta, minute timedelta, seconds timedelta;

3. Verify proper rendering of the calendar:

Scenario 1: Initialize a calendar component
Scenario 2: Initialize a calendar component with id property
Scenario 3: Properly set @Input properties and setters, formatOptions and formatViews
Scenario 4: Properly render calendar DOM structure, year view, month view, day view

4. Verify Calendar select and deselect interactions

Single selection
- Scenario 1: With event
- Scenario 2: Outside of current month - 1, -2 etc
- Scenario 3: Through API
Multiple selection
- Scenario 1: With event
- Scenario 2: Multiple through API
Range selection
- Scenario 1: With event
- Scenario 2: Through API
Deselect scenarios
- Single selection
  - Scenario 1: Deselect with invalid date, should not be doing anything
  - Scenario 2: Deselect with array of one date (or two dates) should throws an error
  - Scenario 3: Select datetime.now and deselect datetime.now
  - Scenario 4: Select datetime.now and deselect another date
- Range selection/deselection - Current Selection should be overriden on new range selection execution. The whole Range Selection should be deselected on Deselect action with dates, part of the selected dates array.
  - Scenario 1: Select a range (this.calendar1.selectDate([new Date('2018-09-26'), new Date('2018-09-28')]) and deselect with bigger range that includes it (this.calendar1.deselectDate([new Date('2018-09-20'), new Date('2018-09-30')]);). Selection should be cleared.
  - Scenario 2: Select a range and deselect with a range which is not in the selection. Selection should not be cleared.
  - Scenario 3: Select a range (this.calendar1.selectDate([new Date('2018-09-26'), new Date('2018-09-28')]) and deselect a range which includes beginning or end of the selection (this.calendar1.deselectDate([new Date('2018-09-20'), new Date('2018-09-27')]);). Selection should be cleared.
  - Scenario 4: Select a range (this.calendar1.selectDate([new Date('2018-09-20'), new Date('2018-09-28')]) and deselect a range in the middle of the selection (this.calendar1.deselectDate([new Date('2018-09-22'), new Date('2018-09-24')]);). Selection should be cleared.
  - Scenario 5: When range type is used, if only one date is passed, there is an error.
  - Scenario 6: Select a range with array of only one date (this.calendar1.selectDate([new Date('2018-09-20')]). This date should be selected, and the previous selection should be overriden.
    - Scenario 7: Deselect a range with array of only one date (this.calendar1.selectDate([new Date('2018-09-20')]) that is part of the Selection range. Selection should be cleared.
  - Scenario 8: Select 5 days this.calendar1.selectDate([new Date('2018-09-26'), new Date('2018-09-28'), new Date('2018-09-22'), new Date('2018-09-10')]); A range between the lowest and the bigger dates should be selected.
  - Scenario 9: Deselect with array with dates this.calendar1.deselectDate([new Date('2018-09-26'), new Date('2018-09-28'), new Date('2018-09-21'),]); The whole Selection should be cleared.
    - Scenario 10: Deselect/Select range with invalid date. Error should be thrown
  - Scenario 11: Select/deselect a range with invalid date and valid dates. A range with the valid dates should be selected/deselected.
- Multi selection/deselection
  - Scenario 1: Select array of 5 days and deselect all 5 days
  - Scenario 2: Select array of 5 days and deselect array of one days
  - Scenario 3: select array of 5 days and deselect array of 3 dates
  - Scenario 4: Select array of 5 days and deselect array of one days that is not part of the array
  - Scenario 5: select array of 5 days and deselect array of 3 dates that are not part of the array
  - Scenario 6: select array of 5 days and deselect one day (not array) Error? Should there be error
  - Scenario 7: select array of 5 days and deselect one day (array) working without errors
  - Scenario 8: select array of 1 day and deselect one day (not array)

5. Verify Keyboard navigation interactions

Scenario 1: PageUp / PageDown
Scenario 2: Home / End / ENTER
Scenario 3: ↑ / ↓ / ← / →

6. Should persist the focus when select date in the (next/prev) month.

7. Should change the focus when select date in the (next/prev) month, when multiple month views are displayed.

8. Disabled dates

Verify dates are disabled for each DateRangeType - Before, After, Between, Specfic, Weekdays, Weekends.
Verify date is disabled when Between DateRangeType is used with the same date items. Example [new Date(2018, 3, 1), new Date(2018, 3, 1)]
Verify date range is disabled when Between DateRangeType is used with dates in switched order. Example [new Date(2018, 3, 1), new Date(2018, 2, 20)];
Verify overlapping ranges; Overlapping ranges should be merged.
Verify disabling recurring patterns, e.g. each 1 day of month;
Verify edge:
- Scenario 1: Between with [new Date()] and [new Date()]
- Scenario 2: Disable/enabe whole year, month and week
- Scenario 3: Disabling/enabling ranges across two years.
Verify difference between special day style and regular non-working days.
Verify style and behavior on disabling selected date. (same for today).
Verify disabled dates are not selected on Range Date selection.

9. Multi View Calendar

Base Tests
- Scenario 1: Component Should render properly when using monthsViewNumber property
- Scenario 2: Component Should render properly when using hideOutside days property
- Scenario 3: Should be able to change hideOutsideDays and monthsViewNumber runtime
- Verify setting of headerTemplate and subheaderTemplate
- Verify calendar can be vertical when monthsViewNumber is set
- Verify setting of weekStart
- Verify event onSelection is fired when select a date
Multi View Calendar KB Navigation
- Scenario 1: Should open years view, navigate through and select an year via KB, new month Should come at correct position
- Scenario 2: Should open months view, navigate through and select a month via KB, new month Should come at correct position
- Scenario 3: Should navigate to the first enabled date from the previous visible month when using Arrow Key Up
- Scenario 4: Should navigate to the first enabled date from the previous visible month when using Arrow Key Left
- Scenario 5: Should navigate to the first enabled date from the previous invisible month when using Arrow Key Up
- Scenario 6: Should navigate to the first enabled date from the previous invisibile month when using Arrow Key Left
- Scenario 7: Should navigate to the first enabled date from the next visible month when using Arrow Key Down
- Scenario 8: Should navigate to the first enabled date from the next invisiblee month when using Arrow Key Down
- Scenario 9: Should navigate to the first enabled date from the next visible month when using Arrow Key Right
- Scenario 10: Should navigate to the first enabled date from the next invisible month when using Arrow Key Right
- Scenario 11: Should preserve the active date on (shift) Page Up and Page Down.
- Scenario 12: Should increment/decrement months continuously on mousedown.
- Scenario 13: Should increment/decrement months continuously on enter keydwon.
- Scenario 14: When navigating to a new month that is coming in view, sand the new month has a selected date, selected date Should not steal the focus
- Scenario 15: When clicking on year/month in the picker, new month should come at the corresponding position, not first Shift + Tab goes to arrow next element after last visible day
- Scenario 16: Page Up+ Page Up/Page Down+ Page Downchanges the view twice, does not lose focus after first change
- Scenario 17: Edge cases like: last two, first two dates are disabled, and navigating to/from them to next visible/invisible months
Multi View Calendar Selection
- Scenario 1: When selection is multi/single, days should be applied igx-calendar-date--selected class in all month views, when hideInactiveDays is false
- Scenario 2: When selection is range, outside days which are part of the range should not be highlighted as selected Should correctly change views using the arrow keys
- Scenario 3: Selecting/Deselecting a date from a month view in multi selection should also select/deselect the date in another view that displays this date
- Scenario 4: When selection is multi and selecting dates should not create a range
- Scenario 5: Should not apply igx-calendar-date--range to any day class when selection is not range Outside days should be applied igx-calendar-date--hidden when hideInactiveDays is set to true
- Scenario 6: Should change days view when selecting an outside day
- Verify that disabled dates cannot be selected when selection is single, range or multi
- Verify API methods selectDate and deselectDate when selection is single
- Verify API methods selectDate and deselectDate when selection is multi
- Verify API methods selectDate and deselectDate when selection is range
Multi-View Calendar Integration
- Verify opening Multi-View Calendar from datepicker
- Verify setting hideOutsideDays and monthsViewNumber from datepicker

5. Keyboard navigation

We follow the Active element navigation methodology, established for the igxGrid kb navigation as well. This pattern reduces the number of tab stops within the interface designed for the igxGrid to a minimum of five stops:

Previous month button
Month selection button
Year selection button
Next month button
Selected date/Current date/First date of the month view (not disabled)

Note: Keep in mind that based on the enabled features and calendar views (Multi-view calendar), the tab stops will be increased.

Behaviors

Tab press behavior:

The tabbable elements are the Navigation buttons*, and based on the Calendar configuration the Selected date or Current date. The selected date takes precedence over the current date.
If Multi-view is set, the navigation will go through all available Navigation buttons* for each calendar view.
If multiple dates are selected, the kb navigation will go only through the first selected date.
If range selection is selected, the kb navigation will go only though the first date part of the range selection.
Disabled dates and special dates are not part of the tab execution sequence.
If no selected/current date is present in the Calendar view the first month of the first (not disabled) visible date of the month view will be focused on Tab key press.

Arrow keys behavior:

Only the Calendar body is navigable with the arrow keys, as well as the Month and Year view. Use enter to perform day, month, and year selection.

If disabled dates are present in the calendar body, these dates will be skipped or arrow keys navigation.
Week numbers and weekday labels are not navigable with the arrow keys.
Arrow keys navigation is used for the Month view and Year view component. Use Enter key to select a month/year.

*List:

Navigation buttons - the buttons part of the top calendar view - Previous month button, Month selection button, Year selection button, Next month button

When the igxCalendar component is focused:

Keys	Description
`PageUp`	Moves to the previous month/s view
`PageDown`	Moves to the next month/s view
`SHIFT` + `PageUp`	Moves to the previous year
`SHIFT` + `PageDown`	Moves to the next year
`Home`	Focuses the first day of the current month that is in view (or earliest month when more than one month view is displayed)
`End`	Focuses the last day of the current month that is in view. (or latest month when more than one month view is displayed)

When a day inside the current month is focused:

Keys	Description
↑ / ↓ / ← / →	Navigates through the days in the month
`ENTER`	Selects the currently focused day
↑ / ↓ / ← / →	Moves to next/previous month after navigating from first/last day in current month when more than one month view is displayed
→ / ↓	Navigating next from the last month will shift the months in the view by the number of month views displayed, and focus will move to first month in the view.
← / ↑	Navigating back from the first month will shift the months in the view by one, and focus will stay in the first view.