Skip to content

Commit 90a80d9

Browse files
crisbetocrisbeto
committed
feat(material/timepicker): add timepicker component
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: ```html <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](https://m3.material.io/components/time-pickers/overview) 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](https://dhutaryan.github.io/ngx-mat-timepicker) 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](https://www.telerik.com/kendo-angular-ui/components/dateinputs/timepicker), [Ignite UI](https://www.infragistics.com/products/ignite-ui-angular/angular/components/time-picker) or [MUI](https://mui.com/x/react-date-pickers/time-picker/), 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.
1 parent 1f06315 commit 90a80d9

18 files changed

+2751
-33
lines changed

‎src/dev-app/timepicker/BUILD.bazel

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,12 @@ ng_module(
1212
deps = [
1313
"//src/material/button",
1414
"//src/material/card",
15+
"//src/material/core",
16+
"//src/material/datepicker",
1517
"//src/material/icon",
18+
"//src/material/form-field",
19+
"//src/material/input",
20+
"//src/material/select",
1621
"//src/material/timepicker",
1722
],
1823
)

‎src/dev-app/timepicker/timepicker-demo.html

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,99 @@
1-
<mat-timepicker/>
1+
<div class="demo-row">
2+
<div>
3+
<div>
4+
<h2>Basic timepicker</h2>
5+
<mat-form-field>
6+
<mat-label>Pick a time</mat-label>
7+
<input
8+
matInput
9+
[matTimepicker]="basicPicker"
10+
[matTimepickerMin]="minControl.value"
11+
[matTimepickerMax]="maxControl.value"
12+
[formControl]="control">
13+
<mat-timepicker [interval]="intervalControl.value" #basicPicker/>
14+
<mat-timepicker-toggle [for]="basicPicker" matSuffix/>
15+
</mat-form-field>
16+
17+
<p>Value: {{control.value}}</p>
18+
<p>Dirty: {{control.dirty}}</p>
19+
<p>Touched: {{control.touched}}</p>
20+
<p>Errors: {{control.errors | json}}</p>
21+
<button mat-button (click)="randomizeValue()">Assign a random value</button>
22+
</div>
23+
24+
<div>
25+
<h2>Timepicker and datepicker</h2>
26+
<mat-form-field>
27+
<mat-label>Pick a date</mat-label>
28+
<input
29+
matInput
30+
[matDatepicker]="combinedDatepicker"
31+
[(ngModel)]="combinedValue">
32+
<mat-datepicker #combinedDatepicker/>
33+
<mat-datepicker-toggle [for]="combinedDatepicker" matSuffix/>
34+
</mat-form-field>
35+
36+
<div>
37+
<mat-form-field>
38+
<mat-label>Pick a time</mat-label>
39+
<input
40+
matInput
41+
[matTimepicker]="combinedTimepicker"
42+
[matTimepickerMin]="minControl.value"
43+
[matTimepickerMax]="maxControl.value"
44+
[(ngModel)]="combinedValue"
45+
[ngModelOptions]="{updateOn: 'blur'}">
46+
<mat-timepicker [interval]="intervalControl.value" #combinedTimepicker/>
47+
<mat-timepicker-toggle [for]="combinedTimepicker" matSuffix/>
48+
</mat-form-field>
49+
</div>
50+
51+
<p>Value: {{combinedValue}}</p>
52+
</div>
53+
54+
<div>
55+
<h2>Timepicker without form field</h2>
56+
<input [matTimepicker]="nonFormFieldPicker">
57+
<mat-timepicker aria-label="Standalone timepicker" #nonFormFieldPicker/>
58+
</div>
59+
</div>
60+
61+
<mat-card appearance="outlined" class="demo-card">
62+
<mat-card-header>
63+
<mat-card-title>State</mat-card-title>
64+
</mat-card-header>
65+
66+
<mat-card-content>
67+
<div class="demo-form-fields">
68+
<mat-form-field>
69+
<mat-label>Locale</mat-label>
70+
<mat-select [formControl]="localeControl">
71+
@for (locale of locales; track $index) {
72+
<mat-option [value]="locale">{{locale}}</mat-option>
73+
}
74+
</mat-select>
75+
</mat-form-field>
76+
77+
<mat-form-field>
78+
<mat-label>Interval</mat-label>
79+
<input matInput [formControl]="intervalControl"/>
80+
</mat-form-field>
81+
82+
<mat-form-field>
83+
<mat-label>Min time</mat-label>
84+
<input matInput [matTimepicker]="minPicker" [formControl]="minControl">
85+
<mat-timepicker #minPicker/>
86+
<mat-timepicker-toggle [for]="minPicker" matSuffix/>
87+
</mat-form-field>
88+
89+
<mat-form-field>
90+
<mat-label>Max time</mat-label>
91+
<input matInput [matTimepicker]="maxPicker" [formControl]="maxControl">
92+
<mat-timepicker #maxPicker/>
93+
<mat-timepicker-toggle [for]="maxPicker" matSuffix/>
94+
</mat-form-field>
95+
</div>
96+
</mat-card-content>
97+
</mat-card>
98+
</div>
99+

‎src/dev-app/timepicker/timepicker-demo.scss

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,22 @@
1-
// TODO
1+
.demo-row {
2+
display: flex;
3+
align-items: flex-start;
4+
gap: 100px;
5+
}
6+
7+
.demo-card {
8+
width: 600px;
9+
max-width: 100%;
10+
flex-shrink: 0;
11+
}
12+
13+
.demo-form-fields {
14+
display: flex;
15+
flex-wrap: wrap;
16+
gap: 0 2%;
17+
margin-top: 16px;
18+
19+
mat-form-field {
20+
flex-basis: 49%;
21+
}
22+
}

‎src/dev-app/timepicker/timepicker-demo.ts

Lines changed: 57 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,68 @@
66
* found in the LICENSE file at https://angular.dev/license
77
*/
88

9-
import {ChangeDetectionStrategy, Component} from '@angular/core';
10-
import {MatTimepicker} from '@angular/material/timepicker';
9+
import {ChangeDetectionStrategy, Component, inject, OnDestroy} from '@angular/core';
10+
import {DateAdapter} from '@angular/material/core';
11+
import {FormControl, FormsModule, ReactiveFormsModule} from '@angular/forms';
12+
import {MatTimepickerModule} from '@angular/material/timepicker';
13+
import {MatFormFieldModule} from '@angular/material/form-field';
14+
import {MatInputModule} from '@angular/material/input';
15+
import {JsonPipe} from '@angular/common';
16+
import {MatButtonModule} from '@angular/material/button';
17+
import {MatSelectModule} from '@angular/material/select';
18+
import {Subscription} from 'rxjs';
19+
import {MatCardModule} from '@angular/material/card';
20+
import {MatDatepickerModule} from '@angular/material/datepicker';
1121

1222
@Component({
1323
selector: 'timepicker-demo',
1424
templateUrl: 'timepicker-demo.html',
1525
styleUrl: 'timepicker-demo.css',
1626
standalone: true,
1727
changeDetection: ChangeDetectionStrategy.OnPush,
18-
imports: [MatTimepicker],
28+
imports: [
29+
MatTimepickerModule,
30+
MatDatepickerModule,
31+
MatFormFieldModule,
32+
MatInputModule,
33+
ReactiveFormsModule,
34+
FormsModule,
35+
JsonPipe,
36+
MatButtonModule,
37+
MatSelectModule,
38+
MatCardModule,
39+
],
1940
})
20-
export class TimepickerDemo {}
41+
export class TimepickerDemo implements OnDestroy {
42+
private _dateAdapter = inject(DateAdapter);
43+
private _localeSubscription: Subscription;
44+
locales = ['en-US', 'da-DK', 'bg-BG', 'zh-TW'];
45+
control: FormControl<Date | null>;
46+
localeControl = new FormControl('en-US', {nonNullable: true});
47+
intervalControl = new FormControl('1h', {nonNullable: true});
48+
minControl = new FormControl<Date | null>(null);
49+
maxControl = new FormControl<Date | null>(null);
50+
combinedValue: Date | null = null;
51+
52+
constructor() {
53+
const value = new Date();
54+
value.setHours(15, 0, 0);
55+
this.control = new FormControl(value);
56+
57+
this._localeSubscription = this.localeControl.valueChanges.subscribe(locale => {
58+
if (locale) {
59+
this._dateAdapter.setLocale(locale);
60+
}
61+
});
62+
}
63+
64+
randomizeValue() {
65+
const value = new Date();
66+
value.setHours(Math.floor(Math.random() * 23), Math.floor(Math.random() * 59), 0);
67+
this.control.setValue(value);
68+
}
69+
70+
ngOnDestroy(): void {
71+
this._localeSubscription.unsubscribe();
72+
}
73+
}

‎src/material/core/tokens/m2/mat/_timepicker.scss

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,30 @@
11
@use '../../token-definition';
2+
@use '../../../theming/inspection';
23
@use '../../../style/sass-utils';
4+
@use '../../../style/elevation';
35

46
// The prefix used to generate the fully qualified name for tokens in this file.
57
$prefix: (mat, timepicker);
68

79
// Tokens that can't be configured through Angular Material's current theming API,
810
// but may be in a future version of the theming API.
911
@function get-unthemable-tokens() {
10-
@return ();
12+
@return (
13+
container-shape: 4px,
14+
container-elevation-shadow: elevation.get-box-shadow(8),
15+
);
1116
}
1217

1318
// Tokens that can be configured through Angular Material's color theming API.
1419
@function get-color-tokens($theme) {
1520
@return (
16-
enabled-trigger-text-color: hotpink,
21+
container-background-color: inspection.get-theme-color($theme, background, card)
1722
);
1823
}
1924

2025
// Tokens that can be configured through Angular Material's typography theming API.
2126
@function get-typography-tokens($theme) {
22-
@return (
23-
trigger-text-font: fantasy,
24-
);
27+
@return ();
2528
}
2629

2730
// Tokens that can be configured through Angular Material's density theming API.

‎src/material/core/tokens/m3/mat/_timepicker.scss

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
@use 'sass:map';
2+
@use '../../../style/elevation';
13
@use '../../token-definition';
24

35
// The prefix used to generate the fully qualified name for tokens in this file.
@@ -10,8 +12,10 @@ $prefix: (mat, timepicker);
1012
/// @return {Map} A set of custom tokens for the mat-timepicker
1113
@function get-tokens($systems, $exclude-hardcoded, $token-slots) {
1214
$tokens: (
13-
enabled-trigger-text-color: hotpink,
14-
trigger-text-font: fantasy,
15+
container-background-color: map.get($systems, md-sys-color, surface-container),
16+
container-shape: map.get($systems, md-sys-shape, corner-extra-small),
17+
container-elevation-shadow:
18+
token-definition.hardcode(elevation.get-box-shadow(2), $exclude-hardcoded),
1519
);
1620

1721
@return token-definition.namespace-tokens($prefix, $tokens, $token-slots);

‎src/material/timepicker/BUILD.bazel

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,16 @@ ng_module(
2020
deps = [
2121
"//src:dev_mode_types",
2222
"//src/cdk/bidi",
23-
"//src/cdk/coercion",
23+
"//src/cdk/keycodes",
24+
"//src/cdk/overlay",
25+
"//src/cdk/platform",
26+
"//src/cdk/portal",
27+
"//src/cdk/scrolling",
28+
"//src/material/button",
2429
"//src/material/core",
30+
"//src/material/input",
2531
"@npm//@angular/core",
32+
"@npm//@angular/forms",
2633
],
2734
)
2835

@@ -45,7 +52,12 @@ ng_test_library(
4552
),
4653
deps = [
4754
":timepicker",
48-
"//src/cdk/bidi",
55+
"//src/cdk/keycodes",
56+
"//src/cdk/testing/private",
57+
"//src/material/core",
58+
"//src/material/form-field",
59+
"//src/material/input",
60+
"@npm//@angular/forms",
4961
"@npm//@angular/platform-browser",
5062
],
5163
)

‎src/material/timepicker/public-api.ts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,8 @@
66
* found in the LICENSE file at https://angular.dev/license
77
*/
88

9-
export * from './timepicker-module';
109
export * from './timepicker';
10+
export * from './timepicker-input';
11+
export * from './timepicker-toggle';
12+
export * from './timepicker-module';
13+
export {MatTimepickerOption, MAT_TIMEPICKER_CONFIG, MatTimepickerConfig} from './util';

0 commit comments

Comments
 (0)