igxCalendar Specification

Calendar Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. Test Scenarios
5. Accessibility
6. Assumptions and Limitations
7. References

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

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

3.3. Globalization/Localization

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

3.4. Keyboard Navigation

When the igxCalendar component is focused:

Keys	Description
PageUp	Moves to the previous month
PageDown	Moves to the next month
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.

• BREAKING CHANGE: When next date to be focused is in previous/next month, and the date is visible both in current month and in previous/next month, it will always focus the date in the corresponding prev/next month. All dates that are not part of the current month will not be focusable.

3.5. API

Inputs

Name	Type	Description
weekStart	Number or WEEKDAYS	Sets which day the week will start.
locale	string	Sets the locale used for formatting and displaying the dates in the calendar. 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. Accessibility

ARIA Support

RTL Support

6. Assumptions and Limitations

Assumptions	Limitation Notes

7. References

Specify all referenced external sources