Date Range Picker (Draft)

Date Range Picker Specification

Contents

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

Owned by

Astrea + Design and Web Development

Developer Name Bozhidara Pachilova, Ivan Kitanov

Designer Name

Requires approval from

• Radoslav Karaivanov | Date:
• Svilen Dimchevski | Date:

Signed off by

• Radoslav Mirchev | Date:
• Platform Architect Name | Date:

Revision History

Version	Users	Date	Notes
1	Bozhidara Pachilova	2025-03-10	Initial draft

1. Overview

The igc-date-range-picker lets users select start and end dates by either typing in its input fields - one for start and one for end (//TODO - they will be editable?; multiple/single input?) or by selecting a date range through a dropdown/dialog popup calendar view.

Objectives

Provide a web component that uses two igc-date-time-inputs (//TODO?) to edit start and end date values and the igc-calendar to select a range value. The igc-calendar is opened either in an igc-popover for dropdown mode, or in an igc-dialog for dialog mode. The value of the igc-date-range-picker is of type (Date | null)[], where the expected length is two and the first date represents a start date, and the second - the end date. (// TODO? - this or new type, similar to DateRange in Angular: const newValue: DateRange = { start: new Date("2/2/2012"), end: new Date("3/3/2013")};`)

Reference specifications: Calendar, Date Time Input, Dialog

End-to-end user experience prototype

Acceptance criteria

The igc-date-range-picker must:

• let users specify a date range by either typing it in two inputs - for start and end value (//TODO) or picking a date range through its calendar component
• display the date-range picker as a single input field, which displays both start and end dates and is readonly // TODO
• opend the calendar by clicking on an input or a toggle icon (//TODO ?)
• have dropdown and dialog modes for opening the calendar
• be form associated and when configured as part of a form, participate in form submission and validation
• expose CSS parts for styling as well as slots for projecting relevant elements such as prefix, suffix, helper text, etc. (// TODO: requirements for two/single inputs, two prefixes, suffixes, clear buttons, etc?)
• provide UI with buttons allowing to quickly select among a predefined set of ranges - last week, last month, etc. (//TODO ?)
• expose configuration properties for modifying/localizing the inputs and display format of the date values in the inputs
• expose configuration properties for modifying/localizing the relevant parts of its calendar component
• have adequate keyboard support for navigation and selection
• support the themes available in the library
• be WAI-ARIA compliant.

2. User Stories

Developer stories: 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, readonly or nonEditable
• 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 inputs (//TODO) both during editing and display, by specifying a custom pattern/mask
• choose the component to render either single input displaying the date range values separated by a symbol ("-") or two inputs for start and end date (//TODO)
• 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
• opt in to show buttons allowing to choose among a predefined set of ranges, such as last week, last month, etc. (// TODO ?)
• be able to style parts of the component according to my prefereces.

End-user stories:

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

• type in and edit a date value inside the start and end inputs in dropdown mode (//TODO)
• select a date range from the calendar picker of the component and have it automatically filled in the input(s)
• identify and distinguish the current date, selected date range, special and disabled dates
• navigate and make edits in the input parts of the component using a keyboard (// TODOS - the current version of the spec assumes the inputs are editable)
• 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
• be informed if the dates I've entered are valid and within range (if such is specified)
• select a range by clicking a button among a set of predefined date ranges (//TODO).

3. Functionality

3.1. End-User Experience

** Integration scenarios or functionality with other features/components prototype ** End-to-end user experienceprototype ** Prepared design files for styling e.g. interplay with features and light/dark variants design hand-off

3.2. Developer Experience

Default initialization

• // TODO - determine how to define labels - via single property like below?

<igc-date-range-picker label="{{ start: 'Start label', end: 'End label' }}"></igc-date-range-picker>

With initial value through attribute - //TODO

Display and input formats

<igc-date-range-picker displayFormat="yyyy-dd-mm" inputFormat="yyyy-dd-mm"></igc-date-range-picker>

Display and input format should be applied for both inputs. (//TODO ?)

For reference of the supported formats - the Date Time Input spec.

Slots

<igc-date-range-picker label="..." mode="dialog" displayFormat="yyyy/MM/dd">
  <p slot="title">...</p>
  <p slot="invalid">Please, select another range</p>
</igc-date-range-picker>

3.3. Behaviors // TODO

1. Selecting a single date from the calendar - this date becomes both start and end date of the selected range; both inputs are filled with it.

• igcChange is emitted; start and end are the same date;

2. Selecting two different dates from the calendar - earlier date becomes start date and later date becomes end; both inputs are filled with them.

• igcChange is emitted; start and end are different dates;

3. Clearing the inputs - is there a clear button that clears both, or separate button for each input?

• igcChange is emitted; start and end are null (detail is [null, null]);

4. Both inputs are initially empty. One of them - the start date, is filled by typing.

• igcInput is emitted; the detail is [dateValue, null]
• On losing focus of the input igcChange is fired; the detail is [dateValue, null]

3.3. Globalization/Localization

3.4. Keyboard Navigation

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

Key combination	Description
Escape	If the picker is shown closes the picker and returns focus to the input part. Otherwise it is a no-op

When any of the input parts of the component is focused: (//TODO - revise once the number and type of inputs is clear)

Key combination	Description
ArrowLeft / ArrowRight	Moves the caret one character in the desired direction
Ctrl + ArrowLeft	Moves the caret to the beginning of the current input mask section or to the start of the previous one it is already at the beginning
Ctrl + ArrowRight	Moves the caret to the end of the current input mask section or to the end of the next one it is already at the end
ArrowUp	Increments by one step the currently "focused" part of the input mask
ArrowDown	Decrements by one step the currently "focused" part of the input mask
Home	Moves the caret at the beginning of the mask
End	Moves the caret at the end of the mask
Ctrl + ;	Sets the current date as the value of the component (start input - start value, end input - end value)
Alt + ArrowDown	Opens the calendar dropdown
Alt + ArrowUp	Closes the calendar dropdown

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

3.5. API

Options

Property	Attribute	Reflected	Property Type	Default	Description
open	open	Yes	boolean	false	Whether the calendar picker is open
mode	mode	No	'dropdown' | 'dialog'	dropdown	Whether to display the calendar picker in a dropdown or a modal dialog
keepOpenOnSelect	keep-open-on-select	Yes	boolean	false	Whether the calendar picker should be kept open on selection
keepOpenOnOutsideClick	keep-open-on-outside-click	Yes	boolean	false	Whether the calendar picker should be kept open when clicking outside of it
value	value	No	//TODO	-	The value of the component
min	min	No	Date	-	The minimum start value required for the component to remain valid
max	max	No	Date	-	The maximum end value allowed for the component to remain valid
required	required	Yes	boolean	false	Makes the component required in a form context
disabled	disabled	Yes	boolean	false	Disables the component
readOnly	readonly	Yes	boolean	false	Makes the component readonly
nonEditable	non-editable	Yes	boolean	false	Whether to allow typing in the input(s)
placeholder	placeholder	No	string	-	The placeholder for the input - //TODO - how to handle this for two inputs?
label	label	No	string	-	The label for the component - //TODO - how to handle this for two inputs?
outlined	outlined	Yes	boolean	false	Whether the input part will have outline appearance in the Material theme
locale	locale	No	string	en	The locale used to display the value and used for formatting the display of the calendar dates
inputFormat	input-format	No	string	Default for locale	Date mask pattern when editing in the input part of the component Reference
displayFormat	display-format	No	string	inputFormat	Date pattern to apply to the input value when the input(s) is not focused Reference
prompt	prompt	No	string	_	The prompt character used for unfilled parts of the input(s) mask
weekStart	week-start	No	typed string	sunday	Sets the start day of the week
showWeekNumbers	show-week-numbers	Yes	boolean	false	Whether to show the number of the week in the calendar days view
hideOutsideDays	hide-outside-days	Yes	boolean	false	Whether to show dates that do not belong to the current month
hideHeader	hide-header	No?	boolean	false	Whether to show the calendar header. Applicable only in dialog mode
headerOrientation	header-orientation	Yes	'vertical' | 'horizontal'	horizontal	Whether to align the calendar header vertically or horizontally. Applicable only in dialog mode.
orientation	orientation	No	'vertical' | 'horizontal'	horizontal	Whether to align multiple months horizontally or vertically
visibleMonths	visible-months	No	number	2	The number of months to show in the calendar days view
disabledDates	-	No	DateRangeDescriptor[]	-	The disabled dates for the calendar picker
specialDates	-	No	DateRangeDescriptor[]	-	The special dates for the calendar picker
activeDate	active-date	No	Date	The current date if not set	Sets the date which is shown in view and is highlighted
resourceStrings	-	No	IgcCalendarResourceStrings	-	Resource strings for localization of the calendar picker
actions?	-	No	//TODO ???	-	API to configure predefined ranges selection

Methods

Name	Type signature	Description
show	(): void	Shows the component picker
hide	(): void	Hides the component picker
toggle	(): void	Toggles between the open state of the picker
clear	(): void	Clears the input parts of the component of any user input
stepUp	(datePart?: DatePart, delta?: number): void	Increments the passed in date part // TODO: not sure if to include this - which input is incremented has to be specified; Angular DRP lacks this
stepDown	(datePart?: DatePart, delta?: number): void	Decrements the passed in date part // TODO: not sure if to include this - which input is incremented has to be specified; Angular DRP lacks this
select	(startDate: Date, endDate?: Date): void	Selects the corresponding date range from the calendar. If no endDate is passed, range is 1 day (only startDate) // TODO?
setCustomValidity	(message: string): void	Sets a custom validation message. As long as message is not empty, the component is considered invalid

Events

Name	Cancellable	Description
igcOpening	Yes	Emitted when the calendar picker is opening
igcOpened	No	Emitted after the picker is shown
igcClosing	Yes	Emitted when the calendar picker is closing
igcClosed	No	Emitted when the calendar picker is closed
igcChange	No	Emitted when the value of the component is changed
igcInput	No	Emitted when typing in the input part(s) of the component

Slots

Name	Description
TODO	Renders ....

CSS Shadow Parts

Part	Description
label	The label wrapper that renders content above the target input.
// TODO

Note

All CSS Parts of the Calendar component can also be used to style the igc-date-range-picker calendar. Keep in mind that the content and the label parts of the calendar component are renamed respectively to calendar-content and calendar-label in the igc-date-range-picker scope.

4. Test Scenarios

Automation

Rendering and initialization

• should be successfully initialized in the DOM (defined and rendered).
• should not set an invalid date range as a value
• should be successfully initialized with an initial value //TODO?
• should be successfully initialized in open state in dropdown mode
• should be successfully initialized in open state in dialog mode
• should pass automated WAI-ARIA tests in closed state
• should pass automated WAI-ARIA tests in open state in dropdown mode
• should pass automated WAI-ARIA tests in open state in dialog mode

Attributes and properties

• should set value through attribute correctly // TODO?
• should show/hide the picker based on the value of the open attribute
• should keep the picker open when keepOpenOnOutsideClick is enabled and a click if fired outside of the component
• should keep the picker open when keepOpenOnSelect is enabled and a selection is made in the calendar picker
• should not allow to modify the value through selection or typing when readOnly is true
• should set properties of the calendar correctly
• should set properties of the input(s) correctly
• should set and render UI for a predefined set of ranges to select // TODO ?
• should render slotted elements

Methods and events

• Verify all API methods are invoked correctly and achieve their purpose.
• Veridy all events are emitted correctly.

Interactions

• Verify the above listed key combinations work as expected. // TODO

Form integration

• should be form associated
• should not participate in form submission if the value is empty/invalid
• should participate in form submission if there is a value and the value adheres to the validation constraints
• should reset to its default value state on form reset
• should reflect disabled ancestor state (fieldset/form)
• should enforce required constraint
• should enforce min value constraint
• should enforce max value constraint
• should invalidate the component if a disabled date is typed it in any of the inputs
• should enforce custom constraint

Validation

• should render validation slots

Note

The rest of the properties/attributes should already be covered by the respective unit tests of the components used in the igc-calendar and igc-date-time-input.

5. Accessibility

ARIA Support

When the component is in dropdown mode, the underlying igc-calendar should have role="dialog"

RTL Support

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

6. Assumptions and Limitations

Assumptions	Limitation Notes

7. References

Specify all referenced external sources