Skip to content

igxCalendar Specification

Hristo Anastasov edited this page May 18, 2022 · 49 revisions

Calendar Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Keyboard navigation
  6. Accessibility
  7. Assumptions and Limitations
  8. 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
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.

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

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

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

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.

ARIA Support

RTL Support

Assumptions Limitation Notes

Specify all referenced external sources

Clone this wiki locally