Skip to content

Calendar Specification

Jump to bottom
Radoslav Karaivanov edited this page Sep 25, 2024 · 15 revisions

Calendar Specification

Contents

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

Owned by

Team: Codex

Developer: Diyan Dimitrov

Designer Name

Requires approval from

  • Peer Developer Name | Date:
  • Design Manager: Stefan Ivanov | Date:

Signed off by

  • Product Owner: Radoslav Mirchev | Date:
  • Platform Architect: Radoslav Karaivanov | Date:

Revision History

Version Users Date Notes
1 Diyan Dimitrov 05-Aug-2021 Initial version
2 Radoslav Karaivanov 08-Mar-2023 Updated active date with selection behavior
3 Radoslav Karaivanov 2024-09-25 Added header-date slot

1. Overview

igc-calendar component 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 igc-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

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

  3. ...

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.

  • 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 be able to change the current view date and selected dates programmatically.

  • Story 8: As a developer, I want to configure the number of months visible in days views, 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 specify vertical or horizontal orientation of multiple months displayed in days view.

  • 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. The non-current month days will always be hidden if there is more than 1 month displayed in days view.

  • Story 11: As a developer, I want to be able to show/hide week numbers via boolean property type.

  • Story 12: As a developer, I want to specify whether the calendar has a header which shows the current selected date/dates. The header is displayed only for single and multiple selection modes.

  • Story 13: As a developer, I want to be able to change the title of the header.

  • Story 14: As a developer, I want to specify vertical or horizontal orientation of the calendar header.

  • Story 13: As a developer, I want to specify the first day of week.

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 control the locale used for formatting and displaying the dates in the calendar.
  • Story 5: As an end-user, I want the calendar to control the date-time components in formatted output.
  • Story 6: As an end-user, I want the calendar to have different calendar views.
  • Story 7: As an end-user, I want the calendar to have "disabled" dates, e.g. past-dates, single dates, holidays.
  • Story 8: 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

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

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

We follow the Active element navigation methodology. This pattern reduces the number of tab stops within the interface to a minimum of five stops:

  • Previous month button
  • Month selection button
  • Year selection button
  • Next month button
  • Active date (the current date or the last date that was navigated using the keyboard)

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

Behaviors

Active date with selection

  • If an initial active date is set the component will abide by it regardless of any value(s) set.
  • If no initial active date is set and no value(s) are set, the component active date will default to the current date.
  • If no initial active date is set but there are value(s) set, the component will set the active date as follows:
    • when selection mode is single: set the active date to the value date;
    • when selection mode is multiple: set the active date to the first date of the value collection;
    • when selection mode is range: set the active date to the start of the date range;

Tab press behavior:

  • The tabbable elements are the Navigation buttons* and the active date.
  • If Multi-view is set, the navigation will go through all available Navigation buttons* for each calendar view.

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.

  • The disabled dates won't be skipped on arrow keys navigation, but they can't be selected.
  • 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/next month/year/years button, Month selection button, Year selection button

When the Calendar 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 one, and focus will stay on the last 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.

3.5. API

Properties

Property Attribute Type Default Description
activeDate active-date Date Sets the date which is shown in view and is highlighted. By default it is the current date.
activeView active-view "days" | "months" | "years" "days" The active view.
disabledDates DateRangeDescriptor[] Gets/sets disabled dates.
formatOptions Pick<DateTimeFormatOptions, "month" | "weekday"> {"month":"long","weekday":"narrow"} The options used to format the months and the weekdays in the calendar views.
headerOrientation header-orientation "vertical" | "horizontal" "horizontal" The orientation of the header.
hideHeader hide-header boolean false Determines whether the calendar hides its header. Even if set to false, the header is not displayed for multiple selection.
hideOutsideDays hide-outside-days boolean false Controls the visibility of the dates that do not belong to the current month.
locale locale string "en" Sets the locale used for formatting and displaying the dates in the calendar.
orientation orientation "vertical" | "horizontal" "horizontal" The orientation of the multiple months displayed in days view.
resourceStrings IgcCalendarResourceStrings {"selectMonth":"Select month","selectYear":"Select year","selectDate":"Select date","selectRange":"Select range","selectedDate":"Selected date","startDate":"Start","endDate":"End","previousMonth":"Previous month","nextMonth":"Next month","previousYear":"Previous year","nextYear":"Next year","previousYears":"Previous {0} years","nextYears":"Next {0} years","weekLabel":"Wk"} The resource strings.
selection selection "single" | "multiple" | "range" "single" Sets the type of date selection.
showWeekNumbers show-week-numbers boolean false Show/hide the week numbers.
size size "small" | "medium" | "large" "large" Determines the size of the component.
specialDates DateRangeDescriptor[] Gets/sets special dates.
value value Date | undefined Тhe current value of the calendar.
Used when selection is set to single.
values values Date[] | undefined Тhe current values of the calendar.
Used when selection is set to multiple or range.
visibleMonths visible-months number 1 The number of months displayed in days view.
weekStart week-start "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" "sunday" Sets the start day of the week.

Methods

None

Events

Event Description
igcChange Emitted when calendar changes its value.

Slots

Name Description
title Renders the title of the calendar header.
header-date Renders content instead of the current date/range in the calendar header.

CSS Parts

Name Description
header The header element.
header-title The header title element.
header-date The header date element.
content The content element which contains the views and navigation elements.
navigation The navigation container element.
months-navigation The months navigation button element.
years-navigation The years navigation button element.
years-range The years range element.
navigation-buttons The navigation buttons container.
navigation-button Previous/next navigation button.
days-view-container The days view container element.
days-view Days view element.
months-view The months view element.
years-view The years view element.
days-row Days row element.
label Week header label element.
week-number Week number element.
week-number-inner Week number inner element.
date Date element.
date-inner Date inner element.
first The first selected date element.
last The last selected date element.
inactive Inactive date element.
hidden Hidden date element.
weekend Weekend date element.
range Range selected element.
special Special date element.
disabled Disabled date element.
single Single selected date element.
preview Range selection preview date element.
month Month element.
month-inner Month inner element.
year Year element.
year-inner Year inner element.
selected Indicates selected state. Applies to date, month and year elements.
current Indicates current state. Applies to date, month and year elements.

4. Test Scenarios

Automation

Calendar Test Scenarios

Calendar Model

  • Verify a proper calendar model:

    • 2021 September with first day set to Sunday.
    • 2021 September with first day set to Sunday and extra week.
    • 2021 September with first day set to Friday.
    • Leap year tests.

  • Verify correct using of utility functions - leap year, timedelta, monthRange

Rendering

  • Rendering of the calendar

    • Renders a calendar component successfully.
    • Setting calendar properties
      • Set multiple visibleMonths and verify the count.
      • Verify showWeekNumbers property is set correctly.
      • Verify calendar orientation is set correctly.
      • Verify weekStart is set correctly.
      • Verify hideOutsideDays property is set correctly.
      • Verify week day and month format is set correctly
    • Properly render calendar DOM structure , year view, month view, day view
    • Multi View Calendar
      • Component Should render properly when using monthsViewNumber property.
      • Component Should render properly when using hideOutside days property.
      • Should be able to change hideOutsideDays and monthsViewNumber runtime.
      • Verify headerOrientation can be vertical when monthsViewNumber is set.
      • Verify calendar can be vertical when monthsViewNumber is set.

  • Calendar header

    • Verify show/hide calendar header.
    • Change calendar header title.
    • Verify calendar header orientation is set correctly.

Calendar interactions

  • Verify calendar select interactions

    • Single selection
    • Multiple selections
    • Range selections

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

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

  • Disable dates

    • Verify dates are disabled for each DateRangeType - Before, After, Between, Specific, Weekdays, Weekends.
    • Verify date is disabled when Between DateRangeType is used with the same date items. Example [new Date(2021, 9, 23), new Date(2021, 9, 23)].
    • Verify date range is disabled when Between DateRangeType is used with dates in switched order. Example [new Date(2021, 9, 28), new Date(2021, 9, 22)];
    • Verify overlapping ranges; Overlapping ranges should be merged.
    • Verify disable/enable whole year, month and week.
    • Verify disable/enable ranges across two years.
    • Multi View Calendar Selection
      • Selecting/Deselecting a date from a month view in multi selection should also select/deselect the date in another view that displays this date.
      • When selection is multi and selecting dates should not create a range.
      • Should change days view when selecting an outside day.
      • Verify that disabled dates cannot be selected when selection is single, range or multi.

Keyboard

  • Verify Keyboard navigation interactions

    • PageUp / PageDown

    • Home / End / ENTER

    • Arrow key navigation: ↑ / ↓ / ← / →

    • 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 invisible 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 invisible 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: 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 13: Page Up + Page Up/Page Down + Page Down changes the view twice, does not lose focus after first change

Events

  • Verify igcChange event is emitted when day is selected.
  • Verify igcActiveDateChange event is emitted when active date is changed.
  • Verify igcRangePreviewDateChange event is emitted when date range is set.
  • Verify igcOutsideDaySelected event is emitted when selected date is not in the current selected month.

5. Accessibility

ARIA Support

RTL Support

6. Assumptions and Limitations

Assumptions Limitation Notes

7. References

Specify all referenced external sources

Clone this wiki locally