Skip to content

Calendar Specification

Jump to bottom
Diyan Dimitrov edited this page Oct 25, 2021 · 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

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

...

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

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

Name Description Type Default value Reflected
weekStart Sets which day the week will start. sunday | monday | tuesday | wednesday | thursday | friday | saturday sunday false
locale Sets the locale used for formatting and displaying the dates in the calendar. string en false
selection Sets the type of selection in the calendar. single | multi | range single false
activeDate Sets the date which is shown in view and is highlighted using keyboard navigation. By default it is the current date. Date false
value Gets/sets the current value of the calendar widget. When selection is set to single, it accepts a single Date object. Otherwise it is an array of Date objects. Date | Date[] undefined false
formatOptions The options used to format the months and the weekdays in the calendar views. `Pick<Intl.DateTimeFormatOptions, 'month' 'weekday'>` { month: 'long', weekday: 'narrow' }
ICalendarFormattingViews { day: false, month: true, year: false } false
hasHeader Gets/sets whether the calendar has header. The header is not displayed for multi selection. boolean true false
headerOrientation Controls the orientation of the header. vertical | horizontal horizontal true
orientation Controls the orientation of the multiple months displayed in days view. vertical | horizontal horizontal false
visibleMonths Controls the number of months displayed in days view. number 1 false
hideOutsideDays Controls the visibility of the dates that do not belong to the current month. When visibleMonths is greater than 1 the outside days are not displayed. boolean false false
activeView Gets/sets the active view days | months | years days false
showWeekNumbers Show/hide the week numbers in the days-view display boolean false false
disabledDates Gets/sets the disabled dates descriptors. DateRangeDescriptor[] undefined false
specialDates Gets/sets the special dates descriptors. DateRangeDescriptor[] undefined false
resourceStrings Gets/sets the resource strings IgcCalendarResourceStrings IgcCalendarResourceStringEN false

Methods

None

Events

Name Description Cancelable Parameters
igcChange Emitted when calendar changes its value. false

Slots

Name Description
title Renders the title of the calendar header.

4. Test Scenarios

Automation

  • Scenario 1:
  • scenario 2:

5. Accessibility

ARIA Support

RTL Support

6. Assumptions and Limitations

Assumptions Limitation Notes

7. References

Specify all referenced external sources

Clone this wiki locally