feat(material/timepicker): add timepicker component

[crisbeto]

Addresses a long-time feature request by adding a component that allows users to select a time. The new component uses a combination of an input and a dropdown to allow users to either type a time or select it from a pre-defined list. Example usage:

<mat-form-field>
  <mat-label>Pick a time</mat-label>
  <input matInput [matTimepicker]="picker"/>
  <mat-timepicker #picker/>
  <mat-timepicker-toggle [for]="picker"/>
</mat-form-field>

Features of the new component include:

• Automatically parses the typed-in value to a date object using the current DateAdapter. Existing date adapters have been updated to add support for parsing times.
• Time values can be generated either using the interval input (e.g. interval="45min") or provided directly through the options input.
• Integrated into @angular/forms by providing itself as a ControlValueAccessor and Validator.
• Offers built-in validation for minimum, maximum and time formatting.
• Offers keyboard navigation support.
• Accessibility implemented using the combobox + listbox pattern.
• Can be used either with mat-form-field or on its own.
• Can be combined with mat-datepicker (docs to follow, see the dev app for now).
• Includes test harnesses for all directives.
• Works with Material's theming system.
• Can be configured globally through an injection token.
• Can be used either as an NgModule or by importing the standalone directives.

FAQ

Why did it take so long?

One of the main reasons why we hadn't provided a timepicker component until now was that there's no
universally-accepted design for what a timepicker should look like.

Doesn't Material Design have a timepicker?

Material Design has had a specification for a timepicker for years, but we didn't want to implement it because:

1. This design is primarily geared towards mobile users on Android. It would look out of place in the desktop-focused enterprise UIs that a lot of Angular developers build.
2. The time dial UI is complicated and can be overwhelming, especially in the 24h variant.
3. The accessibility pattern is unclear, users may have to fall back to using the inputs.
4. It's unclear how the time selection would work on non-Westernized locales whose time formatting isn't some variation of HH:MM.
5. The time dial requires very precise movements if the user wants to select a specific time between others (e.g. 6:52). This can be unusable for users with some disabilities.
6. The non-dial functionality (inputs in a dropdown) don't add much to the user experience.

There are community implementations of the dial design that you can install if you want it for your app.

What are some alternate designs that you considered?

Some libraries like Kendo UI, Ignite UI or MUI, as well as Chrome's implementation of <input type="time"/> appear to have settled on a multi-column design for the dropdown. We didn't want to do something similar because:

1. The selected state is only shown using one sensory characteristic (color) which is problematic for accessibility. While we could either add a second one (e.g. a checkbox) or adjust the design somehow, we felt that this would make it look sub-optimal.
2. The UI only looks good on smaller sizes and when each column has roughly the same amount of text. Changing either for a particular column can throw off the whole UI's appearance.
3. It requires the user to tab through several controls within the dialog.
4. It's unclear how the time selection would work on non-Westernized locales whose time formatting isn't some variation of HH:MM.
5. Each column requires a lot of filler whitespace in order to be able to align the selected states to each other which can look off on some selections.

Why this design?

We chose the current design, because:

1. Users are familiar with it, e.g. Google Calendar uses something similar for their time selection.
2. It reuses the design from existing Material Design components.
3. It uses an established accessibility pattern (combobox + listbox) and it doesn't have the same concerns as the multi-column design around indicating the selected state.
4. It allows us to support a wide range of locales.
5. It's compact, allowing us to do some sort of unified control with mat-datepicker in the future.

Fixes #5648.

[github-actions]

Deployed dev-app for 3c27b91 to: https://ng-dev-previews-comp--pr-angular-components-29806-dev-fxh7qbvt.web.app

Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt.

[naaajii]

just a thought: setting minimum time to 12PM, maximum time to 3PM & interval to something like 40m doesn't show the last time 3PM (max) in dropdown.

[crisbeto]

That's a good point, although then the last option won't have the same interval as the rest. This can be worked around by using the options input instead or tweaking the interval.

[andrewseguin]

This part seems surprising to me. Why does ESCAPE clear the input? The datepicker doesnt do this

[crisbeto]

I got this off the W3C example:

Escape
If the listbox is displayed, closes it
If the listbox is not displayed, clears the textbox.

[andrewseguin]

What happens if this function is called twice? Should we save the return result from effect (is there one?) to assert against if this is called more than once

[crisbeto]

I didn't put any safeguards, because it's a private function and the effect will throw if the function is called outside of the constructor.

[andrewseguin]

Im rusty on my rxjs, but should these be unsubscribed at some point

[crisbeto]

Normally we would, but outputs get completed automatically on destroy: https://github.com/angular/angular/blob/main/packages/core/src/authoring/output/output_emitter_ref.ts#L40

[andrewseguin]

This seems clunky - seems like the effect API is missing a way for users to do this more naturally

[crisbeto]

It's definitely clunky, I've raised it with the folks working on reactivity.

[AntonGorelov]

Hello everyone! I believe I found a bug and thought I'd let you know about it.

In the deployed application at the link above, selecting a one-second interval is likely to cause a memory leak.

Steps for reproduce:

1. select 1s interval
2. Click on the timepicker button.

And this is an expected bug, most likely. The number of options in select increases a lot. I would suggest to change the input method for this option. It is up to the user to select or manually enter the hours/minutes/seconds in each input separately. For example, as specified in the Material spec.
In this case there is a separate input for entering hours/minutes/seconds.

[crisbeto]

The list of options is only there to make it easier for the user, it's not used for validation. If you wanted to allow the user to enter seconds, you'd just have to change the accepted time format to include seconds.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}