Time Picker Specification

Owned by

Team Name

Developer Name

Yoanna Ivanova

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date: 6 Apr 2021

Signed off by

Radoslav Mirchev | Date: 15 Mar 2021
Damyan Petev | Date:

Revision History

Version	Users	Date	Notes
1	Names of Developers and Designers	Date

1. Overview

IgxTimePicker - Angular native time picker widget, that lets users input or select a time portion. The display and input formats are customizable.

In dropdown mode, which is the default one, the input field is editable and the user can type time or select one from the dropdown that appears below the input field.

In dialog mode the user experience includes a read-only input that holds time in the following format by default - hh:mm tt. Clicking on the input will result in a dropdown pop-up that holds time portions from which the end-user may select a value.

Here is the basic definition of an igx-time-picker:

<igx-time-picker [(ngModel)]="time">
    <label igxLabel>Select time</label>
</igx-time-picker>

Objectives

Selecting a time portion from the dropdown
Dropdown mode (by default) and dialog mode for the dropdown
Typing, pasting, dragging, and dropping a time string (in a pre-defined format) into the editor (dropdown mode)
Support for min and max value, custom validation with bound model
Model binding
Customizable input mask and display format
Localization
Keyboard navigation in the editor with specified key combinations for expanding and collapsing of the dropdown (dropdown mode) igxDateTimeEditor keyboard navigation
Keyboard/mouse navigation through each time portion in the editor and the dropdown
Changing the orientation of the dropdown's header (dialog mode only) - horizontal or vertical
Customizable positioning and open/close animation of the dropdown
Customizable action buttons
ARIA support

Changing the label, prefixes, suffixes, hint and action buttons

Setting the label:

<igx-time-picker>
    <label igxLabel>Custom Label</label>
</igx-time-picker>

The igxPrefix and igxSuffix directives may be used to project elements before and after the input field.

You can add multiple instances of the igxPrefix and igxSuffix directives which will stack one after the other. For example, these could be used to provide the end-user with the ability to spin a time portion with two buttons. Also, having projected icons like this will not affect the default toggle icon.

<igx-time-picker #picker>
    <igx-icon (click)="picker.increment(DatePart.Minutes, 2)" igxSuffix>expand_more</igx-icon>
    <igx-icon (click)="picker.decrement(DatePart.Minutes, 2)" igxSuffix>expand_less</igx-icon>
</igx-time-picker>

The igxHint directive provides the opportunity to place a helper text below the input. It will be displayed at the beginning or at the end of the input depending on the value of the position property.

<igx-time-picker #picker>
    <igx-hint position="start">Ex.: 09:20:00</igx-hint>
</igx-time-picker>

Additionally, the IgxPickerToggleComponent can be used as wrapper around a projected element. This adds a default click handler to it. It should also be mentioned that this acts as an override to the default toggle icon and as such it can not be stacked.

<igx-time-picker>
    <igx-picker-toggle igxPrefix>
       <igx-icon>access_time</igx-icon>
    </igx-picker-toggle>
</igx-time-picker>

The default action buttons(OK and Cancel) in the drop down can be customized by using ng-template.

<igx-time-picker #picker [value]="date">
    <ng-template igxPickerActions>
        <div class="action-buttons">
            <button igxButton="flat" (click)="selectCurrentTime(picker)">Current Time</button>
        </div>
    </ng-template>
</igx-time-picker>

Acceptance criteria

All user stories must be satisfied.

2. User Stories

Developer stories:

Story 1: As a developer, I want to be able to choose whether to show the picker in a dropdown or a dialog.
Story 2: As a developer, I want to be able to set the default time format.
Story 3: As a developer, I want to be able to set the time format based on users' locale.
Story 4: As a developer, I want to have support for 12H/24H with a 12-hour clock format AM/PM accordingly.
Story 5: As a developer, I want to be able to set whether the seconds, minutes, and hour spinning will wrap around.
Story 6: As a developer, I want to be able to set the delta by which hour and minute items will be changed.
Story 7: As a developer, I want to be able to set a time range to limit user selection within that range.
Story 8: As a developer, I want to be able to customize the handling in case the user selects time outside the allowed range.
Story 9: As a developer, I want to be able to bind ngModel to the time picker.
Story 10: As a developer, I want to have a mechanism for canceling the opening and closing of the time picker dropdown/dialog.
Story 11: As a developer, I want to be able to provide custom formatting functionality.
Story 12: As a developer, I want to be able to set the label of the time picker input field.
Story 13: As a developer, I want to be able to customize the style and look of the input field.
Story 14: As a developer, I want to have a default template that does not require any additional configuration.
Story 15: As a developer, I want to be able to customize the buttons shown on the picker interface.
Story 16: As a developer, I want to be able to change the header orientation to horizontal or vertical (dialog mode only).
Story 17: As a developer, I want to be able to customize the position and animation of the dropdown.

End-user stories:

Story 1: As an end-user, I want to be able to visually differentiate the selected time.
Story 2: As an end-user, I want to have a clear visual highlighting of the currently focused time portion.
Story 3: As an end-user, I want to be able to select the desired time from a dropdown/dialog.
Story 4: As an end-user, I want to be able to navigate the time portions and change their values via the keyboard arrow keys or by scrolling in the input field and in the dropdown/dialog.
Story 5: As an end-user, I want to be able to edit the time portions in the input (dropdown mode only).
Story 6: As an end-user, I want to be able to discard any changes via the cancel button (identical behavior hitting the ESC key).
Story 7: As an end-user, I want to be able to confirm my current time selection via the OK button or a click outside the picker (identical behavior hitting the ENTER key).
Story 8: As an end-user, I expect to have a clear indication of when a range is specified to limit the possible selections (if such is specified).
Story 9: As an end-user, I want to be informed if the time I've entered is valid.
Story 10: As an end-user, I want to be able to clear the selected time.
Story 11: As an end-user, I expect to see time in my locale standard e.g. 12hr mode with AM/PM vs. a 24hr mode.

3. Functionality

Time input or selection
- When IgxTimePicker is in a dropdown mode (default mode), the user can either type a time portion in the input field, select time from its dropdown by mouse click or navigate each time portion in the dropdown by arrow keys or mouse wheel. In dialog mode, the input is read-only so the user can select a time portion from its dropdown by mouse click or time portions navigation.
- The user can navigate each time portion in the dropdown/dialog by arrow keys or mouse wheel. Pressing the confirmation button OK (by default)/the enter key, or clicking outside the dropdown/dialog will confirm the selected value and close the dropdown/dialog. Pressing the CANCEL button (by default) or escape key will revert any selection made to the time picker's value at the moment of dropdown/dialog opening.
- When the value is a string pressing the clear button will set it to null. However if the value is a Date object, pressing the clear button will reset the time to 00:00:00.
Dropdown/Dialog
- Displays time portions within min/max range if any or time between 00:00 and 24:00. The displayed values for each time portion are calculated based on the items delta always starting from zero. For example if minutes delta is set to 20, the displayed minutes will be 0, 20, 40 and 60. If the minValue/maxValue does not match the items delta, the displayed values will start/end from the next/last possible value that matches the threshold.
- Selected time highlight (incl. header in dialog mode).
- On dropdown/dialog opening the selected time will reflect the picker's value. However, in cases when the value is null, is outside the min/max range or does not match the items delta, the selected value in the dropdown/dialog will be the minimum possible value or the closest value that match items delta.
- Each time portion navigation
Custom date display format
- The IgxTimePicker makes use of IgxDateTimeEditor which allows passing in of display format based on Angular DatePipe's standards.
- Custom formatting can be applied using the inputFormat property.
- In case the inputFormat property is not set, the applied input format of the underlying editor is inferred from displayFormat, if set and if it contains only numeric date-time parts.
- The input and display formats are adjusted based on the locale. For instance, day period time part (AM/PM or a/p) would not be displayed for locales that do not require it.
Time Validation (min/max check)
- Min and max values can be set which can configure the validity of the picker. In that case the picker's UI will display only the time parts that are within the min-max range. If a time span that is outside of the specified range is written in the editable editor, the picker will become invalid after blurring (by default).

3.1. End-User Experience

A user can select a time from the dropdown, be it in dropdown or dialog mode. In dropdown mode, the user will additionally be able to type, copy/paste, drag/drop values in the input field. The input field can be focused by either clicking on the textbox or the label. Opening of the dropdown menu is achieved by clicking on the toggle icon or via the keyboard. In dialog mode, the input will always be read-only, and clicking anywhere on it opens the dialog. The user can navigate each time portion separately with arrow keys or mouse wheel. While in dialog mode time portion navigation is possible only from the picker interface, in dropdown mode this is possible in both the dropdown and the input. The caret position in the input signifies which time portion will be incremented/decremented. A header is shown only in dialog mode displayed in a horizontal or vertical orientation.

Filled Input Dropdown/Dialog Mode

Focused Input in Editable Dropdown Mode

Dropdown Mode (default) 12H

Dialog Mode 12H (the header in horizontal orientation)

Dialog Mode 12H (the header in vertical orientation)

3.2. Developer Experience

By default, the time picker will be in a dropdown mode with an editable input. Templating of icons, hint, etc. is achieved through content projection.

3.3. Globalization/Localization

locale property
supports date pipe formats

3.4. Keyboard Navigation

Keys	Description
`Space`	Opens the dropdown/dialog picker interface and focuses it
`Alt` + `↓`	Opens the dropdown picker interface and focuses it
`Esc`	Closes the dropdown/dialog, and focuses the last focused input field
`Enter`	Closes the dropdown/dialog, accepts selected time and moves the focus to the last focused input field
`Alt` + `↑`	Closes the dropdown/dialog and focuses the last focused input field

For keyboard navigation inside of an editable editor please refer to IgxDateTimeEditorDirective specification

Validation

The Time Picker integrates with Angular's Form Control allowing ngModel and formControlName directives to be applied on the component. Given that, when the underlying model becomes invalid the Time Picker will reflect that visually. This allows for any built-in (e.g. required) as well as custom validators applied to be reflected in the component state. The Time Picker also implements the Validator interface so the minValue and maxValue options will also affect the validity of the model (rather than just the editor).

3.5. API

Options

Name	Description	Type
cancelButtonLabel	Sets the text of the cancel button label.	string
disabled	Disables or enables the picker.	boolean
displayFormat	The display value of the editor.	string
headerOrientation	Determines whether the dialog's header renders in `vertical` or `horizontal` state. Applies only in `dialog` mode.	'horizontal' \| 'vertical'
id	Sets the value of the id attribute.	string
inputFormat	The format that the editor will use to display the time.	string
maxValue	The maximum time value that can be set.	Date \| string
minValue	The minimum time value that can be set.	Date \| string
mode	Sets whether `IgxTimePickerComponent` is in dialog or dropdown mode.	InteractionMode
okButtonLabel	Sets the text of the ok button label.	string
outlet	The container used for the pop-up element.	IgxOverlayOutletDirective \| ElementRef
overlaySettings	Changes the default overlay settings used by the `IgxTimePickerComponent`.	OverlaySettings
placeholder	Sets the placeholder text for empty input.	string
spinDelta	Sets the threshold by which each time portion would be changed.	object
spinLoop	Sets whether the time spinning will wrap around. Default is `true`.	boolean
tabindex	The editor's tabindex.	number
value	The value of the time picker.	Date

Methods

Name	Description	Return type
open	Opens the dropdown.	void
close	Closes the dropdown.	void
toggle	Toggles the dropdown between opened and closed states.	void
select	Accepts a Date object or string and selects the corresponding time from the dropdown.	void
clear	Clears/resets the picker's time	void
increment	Increments a given `DatePart` by a given threshold.	void
decrement	Decrements a given `DatePart` by a given threshold.	void

Events

Name	Description	Emitted with
opening	Fired when the dropdown has started opening, cancelable.	IBaseCancelableBrowserEventArgs
opened	Fired after the dropdown has opened.	IBaseEventArgs
closing	Fired when the dropdown has started closing, cancelable.	IBaseCancelableBrowserEventArgs
closed	Fired after the dropdown has closed.	IBaseEventArgs
valueChange	Emitted when the picker's value changes. Allows two-way binding of `value`.	Date \| string
validationFailed	Emitted when a user enters an invalid time string or when the value is not within a min/max range.	ITimePickerValidationFailedEventArgs

API Reference:

4. Test Scenarios

Interaction

Scenario 1: Toggle icon should open/close the dropdown and keep the current selection.
Scenario 2: Alt + ArrowDown keys should open the dropdown; outside click closes it and the input accepts current selection.
Scenario 3: Space key opens the dropdown; Enter key closes it and the input accepts current selection.
Scenario 4: Escape key closes the dropdown discarding the selected time in it.
Scenario 5: While the dropdown is open clicking outside the dropdown closes it and accepts the current selection.
Scenario 6: In dialog mode outside click while the dialog is open closes it and accepts the current selection.
Scenario 7: Selecting time from the dropdown should trigger valueChange event.
Scenario 8: Clear button resets the time value if the value is Date and clear it (set to null) if it is a string.
Scenario 9: When value is '00:00:00' or null pressing the clear button does not emit valueChange event.
Scenario 9: User is able to increase and decrease each time portion in the input, depending on the current caret position, using:
- arrows
- mouse wheel
Scenario 10: User is able to increase and decrease each time portion in the UI, depending on the current caret position, using:
- arrows
- mouse wheel
Scenario 11: User can navigate through time portions with arrow keys. If in dropdown mode the values in the input should change accordingly.
Scenario 12: Setting spinLoop to false should stop looping the drop-down over "00:00" for the hours and "00" - "60" for the minutes.
Scenario 13: Setting spinLoop to false should not accept values from the drop-down before/over the min/max values when they are set.
Scenario 14: Setting spinLoop to false should prevent scrolling with mouse/arrows the input before/over the min/max values if they are set. If they are not set it should break at "00:00" for the hours and "00" - "60" for the minutes.
Scenario 15: Should spin over time portions with the spinDelta value.
Scenario 16: When setting the spinDelta to an invalid value, it should default to {hours: 1, minutes: 1, seconds: 1}.
Scenario 17: When spinLoop enabled in 12-hour format iterating over hours should loop from "11PM" to "12AM".

Rendering

Scenario 1: All input properties are initialized with their default values.
Scenario 2: Should be able to change the dropdown mode at runtime.
Scenario 3: Selected times are highlighted.
Scenario 4: When in dialog mode, the selected time should be displayed in the dialog header.
Scenario 5: When disabled the 'disabled' class is applied to the input.
Scenario 6: All aria attributes should be applied correctly.
Scenario 7: Should apply an input format on the editor as per the displayFormat property if it contains only numeric date/time parts and inputFormat is not set.
Scenario 8: Should resolve to the default locale-based input format for the editor in case inputFormat or displayFromat are not set.

API

Scenario 1: All ControlValueAccessor interface methods are correctly implemented.
Scenario 2: The open() method opens the dropdown and triggers opening and opened events.
Scenario 3: The close() method closes the dropdown and triggers closing and closed events.
Scenario 4: The toggle() method opens/closes the dropdown and triggers opening/closing and opened/closed events.
Scenario 5: Increment() and decrement() methods should change date parts correctly.
Scenario 6: Opening and closing events are cancelable.
Scenario 7: Selecting time within the minValue and maxValue range sets the value and fires valueChange event.
Scenario 8: Selecting time outside the minValue and maxValue range triggers validationFailed event.

5. Accessibility

ARIA Support

The IgxTimePickerComponent is decorated with the following properties:

Input ARIA

role is combobox
aria-haspopup is dialog
aria-expanded - indicates the expanded state of the dropdown
aria-labelledby - which relates to a specified label
autocomplete is off to prevent the browser from remembering previous inputs (when editable)
the default toggle icon will have a title that is initially set to Choose Time, after selecting time from the picker, it will change to Change Time, clearing the picker's value will revert the title back to its initial state
aria-required - indicates whether the picker is required

Dropdown/dialog selected time ARIA

role is spinbutton
aria-label - reflects the type of the time portion (hour, minutes, seconds, ampm)
aria-valuenow - the current value of the time portion
aria-valuemin - the minimum possible value of the time portion
aria-valuemax - the maximum possible value of the time portion