• Date-picker specification
  • Owned By
    • Requires approval from:
    • Signed off by:
    • Revision history
  • Overview
    • Acceptance criteria
  • User stories
    • End-user stories
    • Developer stories
  • Functionality
    • End-user experience
    • Developer experience
      • Default initialization
      • With initial value through attribute
      • Slots
    • Behaviors
    • Localization
      • Input format
      • Display format
    • Keyboard navigation
  • API
    • Properties
    • Methods
    • Events
    • Slots
    • CSS Shadow Parts
  • Test scenarios
    • Automation
      • Rendering and initialization
      • Attributes and properties
      • Methods
      • Interactions
      • Form integration
  • Accessibility
    • ARIA
      • References
    • RTL
  • Assumptions and limitations

Team Name: Astrea + Design and Web Development

Developer name: Bozhidara Pachilova

Designer name: Dilyana Dimova

• Damyan Petev
• Svilen Dimchevski

• Simeon Simeonov
• Radoslav Mirchev

The igc-datepicker lets users select a date by either typing it in its input field or by selecting it through a dropdown/dialog popup calendar view.

The igc-datepicker must:

• let users input a date by either typing it in or picking one through its calendar component.
• be form associated and when configured as part of a form, participate in form submission and validation.
• expose configuration properties for modifying/localizing the input and display format of the date value in the input part.
• expose configuration properties for modifying/localizing the relevant parts of its calendar component.
• have adequate keyboard support for navigation and selection.
• be WAI-ARIA compliant.

As an end-user I expect to be able to:

• type in a date value inside the component
• select a date from the calendar picker of the component
• identify and distinguish the current date, selected date, special and disabled dates
• navigate and make edits in the input part of the component using a keyboard
• navigate and make selection in the calendar picker part of the component using a keyboard
• navigate in and out of the component using only a keyboard

As a developer I expect to be able to:

• set an initial value for the component and/or change the value of the component programmatically if need be
• set the interaction state of the component - make it disabled and/or readonly
• set additional properties such as label, placeholder and/or validators in order to enrich and guide the end user experience
• use the component in a standard form and have the component participate in form submission and validation
• choose whether the calendar picker would be a dropdown like experience or a dialog like experience
• control how the date value would be formatted in the input both during editing and display, by specifying a custom pattern/mask
• hide/show days outside of the current month in the calendar picker
• set the day that weeks would start in the calendar picker
• set whether to show/hide week numbers in the calendar picker
• set special/disabled dates in the calendar picker
• set the number of months rendered in the calendar picker
• set the formatting and localization of dates and elements in the calendar picker
• listen and react to user interactions through events on the component.

Design Handoff

<igc-datepicker label="Start date"></igc-datepicker>

<igc-datepicker label="..." value="2024-01-01"></igc-datepicker>

<igc-datepicker label="..." mode="dialog" displayFormat="yyyy/MM/dd">
  <p slot="title">...</p>
  <button slot="actions" @click="${...}">Set today</button>
</igc-datepicker>

1. When the non-editable attribute is set, the input part of the component is transformed into a read-only field. Selection is still available through the calendar picker.

2. When the readonly attribute is set, the input part of the component is transformed into a read-only field. The picker part allows navigation but no selection.

3. When there are disabledDates set and the component input is editable, typing in a disabled date must invalidate the component.

4. When the min or max attributes are set, the calendar widget will display dates outside of those constraint ranges as disabled, meaning the end-user won't be able to select them.

5. Once focus is inside the calendar subsequent keyboard navigation should trap focus inside the calendar widget until the user selects a date, presses Escape or clicks outside of the component.

6. When the component is configured in dropdown mode, no calendar header is rendered while in dialog mode this is controlled through the hide-header attribute.

The igc-datepicker supports specifying an input mask pattern to customize and guide the end-user typing in the input part of the component.

Mask tokens

Similar to the inputFormat, the displayFormat property allows for specifying how the value of the component will be displayed in the input while not editing. It supports a mask pattern and a few predefined formats.

Mask tokens

For the date value of 2024-07-09:

For the predefined formats, the result depends on the locale of the component.

Predefined

For the date value of 2024-07-09 with locale set to 'en':

As long as focus is within parts of the date picker component:

When the input part of the component is focused:

When focus is within the calendar picker, the keyboard navigation follows the behaviors described in this section of the calendar specification.

1. should be successfully initialized in the DOM (defined and rendered).
2. should be successfully initialized with an initial value
3. should be successfully initialized in open state in dropdown mode
4. should be successfully initialized in open state in dialog mode
5. should render slotted elements - prefix, suffix, clear-icon, calendar-icon, helper-text, title, actions
6. should pass automated WAI-ARIA tests in closed state
7. should pass automated WAI-ARIA tests in open state in dropdown mode
8. should pass automated WAI-ARIA tests in open state in dialog mode

1. should show/hide the picker based on the value of the open attribute
2. should keep the picker open when keepOpenOnOutsideClick is enabled and a click if fired outside of the component
3. should keep the picker open when keepOpenOnSelect is enabled and a selection is made in the calendar picker

1. should open the picker on calling show()
2. should close the picker on calling hide()
3. should toggle the open state of the picker on calling toggle()

1. should open the calendar picker on Alt + ArrowDown
2. should close the calendar picker on Alt + ArrowUp
3. should close the picker when in open state on pressing Escape
4. should correctly trap keyboard navigation focus once focus is inside the calendar

1. should be form associated
2. should not participate in form submission if the value is empty/invalid
3. should participate in form submission if there is a value and the value adheres to the validation constraints
4. should reset to its default value state on form reset
5. should reflect disabled ancestor state (fieldset/form)
6. should enforce required constraint
7. should enforce min value constraint
8. should enforce max value constraint
9. should invalidate the component if a disabled date is typed it in the input
10. should enforce custom constraint

• when the component is in dropdown mode, the underlying igc-calendar should have role="dialog"
• the calendar should be labelled by the input part of the component

https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/

The component should work in a Right-To-Left context without additional setup or configuration.

None applicable