Skip to content

Calendar Specification

Jump to bottom
Diyan Dimitrov edited this page Aug 4, 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. 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.
  • Story 12: As a developer, I want the calendar to have templating capabilities ???

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

3.5. API

Properties

Name Description Type Default value Reflected
weekStart Sets which day the week will start. number | WEEKDAYS 0 (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
viewDate 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. 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 Controls whether the date components in the different calendar views should be formatted according to the provided locale and formatOptions. ICalendarFormattingOptions { day: 'numeric', month: 'short', weekday: 'short', year: 'numeric' } false
?formatViews Controls whether the date components in the different calendar views should be formatted according to the provided locale and formatOptions. ICalendarFormattingViews { day: false, month: true, year: false } false
hasHeader Gets/sets whether the calendar has header. boolean true false
?headerAlignment Controls the alignment of the header. vertical | horizontal horizontal ?true
?monthsViewNumber/monthViewsNumber Controls the number of month views displayed. number 1 false
hideOutsideDays Controls the visibility of the dates that do not belong to the current month. boolean false false
?activeView 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

Methods

Name Description Return type Parameters
selectDate Selects day(s) based on the selection type. void value: Date | Date[]
deselectDate Deselects day(s) based on the selection type. void value?: Date | Date[]

Events

Name Description Cancelable Parameters
igcChange Emitted when calendar changes its value. false
igcViewDateChange Emitted when viewDate changes. false
igcActiveViewChange Emitted when activeView changes. false

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