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

Team: Codex

Developer: Diyan Dimitrov

Designer Name

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

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

Version	Users	Date	Notes
1	Diyan Dimitrov	05-Aug-2021	Initial version
2	Radoslav Karaivanov	08-Mar-2023	Updated active date with selection behavior

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.

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

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

3. ...

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.

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

3.1. End-User Experience

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

3.2. Developer Experience

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.

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

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

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

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)

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

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.

None

Event	Description
igcChange	Emitted when calendar changes its value.

Name	Description
title	Renders the title of the calendar header.

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.

Automation

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

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

• 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

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

ARIA Support

RTL Support

Assumptions	Limitation Notes

Specify all referenced external sources