docs(material/timepicker): add timepicker documentation and live exam…

…ples

Populates the timepicker's guide and add live examples.

src/components-examples/material/timepicker/BUILD.bazel

@@ -15,8 +15,15 @@ ng_module(
     deps = [
         "//src/cdk/testing",
         "//src/cdk/testing/testbed",
+        "//src/material/button",
+        "//src/material/datepicker",
+        "//src/material/form-field",
+        "//src/material/icon",
+        "//src/material/input",
         "//src/material/timepicker",
         "//src/material/timepicker/testing",
+        "@npm//@angular/common",
+        "@npm//@angular/forms",
         "@npm//@angular/platform-browser",
         "@npm//@types/jasmine",
     ],

src/components-examples/material/timepicker/index.ts

@@ -1,2 +1,8 @@
 export {TimepickerOverviewExample} from './timepicker-overview/timepicker-overview-example';
+export {TimepickerFormsExample} from './timepicker-forms/timepicker-forms-example';
+export {TimepickerDatepickerIntegrationExample} from './timepicker-datepicker-integration/timepicker-datepicker-integration-example';
+export {TimepickerValidationExample} from './timepicker-validation/timepicker-validation-example';
+export {TimepickerOptionsExample} from './timepicker-options/timepicker-options-example';
+export {TimepickerCustomIconExample} from './timepicker-custom-icon/timepicker-custom-icon-example';
+export {TimepickerLocaleExample} from './timepicker-locale/timepicker-locale-example';
 export {TimepickerHarnessExample} from './timepicker-harness/timepicker-harness-example';

src/components-examples/material/timepicker/timepicker-custom-icon/timepicker-custom-icon-example.html

@@ -0,0 +1,8 @@
+<mat-form-field>
+  <mat-label>Pick a time</mat-label>
+  <input matInput [matTimepicker]="picker">
+  <mat-timepicker-toggle matIconSuffix [for]="picker">
+    <mat-icon matTimepickerToggleIcon>globe</mat-icon>
+  </mat-timepicker-toggle>
+  <mat-timepicker #picker/>
+</mat-form-field>

src/components-examples/material/timepicker/timepicker-custom-icon/timepicker-custom-icon-example.ts

@@ -0,0 +1,16 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {MatTimepickerModule} from '@angular/material/timepicker';
+import {MatIcon} from '@angular/material/icon';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {provideNativeDateAdapter} from '@angular/material/core';
+
+/** @title Timepicker with custom toggle icon */
+@Component({
+  selector: 'timepicker-custom-icon-example',
+  templateUrl: 'timepicker-custom-icon-example.html',
+  providers: [provideNativeDateAdapter()],
+  imports: [MatFormFieldModule, MatInputModule, MatTimepickerModule, MatIcon],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TimepickerCustomIconExample {}

src/components-examples/material/timepicker/timepicker-datepicker-integration/timepicker-datepicker-integration-example.css

@@ -0,0 +1,3 @@
+mat-form-field {
+  margin-right: 16px;
+}

src/components-examples/material/timepicker/timepicker-datepicker-integration/timepicker-datepicker-integration-example.html

@@ -0,0 +1,18 @@
+<mat-form-field>
+  <mat-label>Meeting date</mat-label>
+  <input matInput [matDatepicker]="datepicker" [(ngModel)]="value">
+  <mat-datepicker #datepicker/>
+  <mat-datepicker-toggle [for]="datepicker" matSuffix/>
+</mat-form-field>
+
+<mat-form-field>
+  <mat-label>Meeting time</mat-label>
+  <input matInput
+    [matTimepicker]="timepicker"
+    [(ngModel)]="value"
+    [ngModelOptions]="{updateOn: 'blur'}">
+  <mat-timepicker #timepicker/>
+  <mat-timepicker-toggle [for]="timepicker" matSuffix/>
+</mat-form-field>
+
+<p>Value: {{value}}</p>

src/components-examples/material/timepicker/timepicker-datepicker-integration/timepicker-datepicker-integration-example.ts

@@ -0,0 +1,26 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {FormsModule} from '@angular/forms';
+import {MatTimepickerModule} from '@angular/material/timepicker';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {provideNativeDateAdapter} from '@angular/material/core';
+import {MatDatepickerModule} from '@angular/material/datepicker';
+
+/** @title Timepicker integration with datepicker */
+@Component({
+  selector: 'timepicker-datepicker-integration-example',
+  templateUrl: 'timepicker-datepicker-integration-example.html',
+  styleUrl: './timepicker-datepicker-integration-example.css',
+  providers: [provideNativeDateAdapter()],
+  imports: [
+    MatFormFieldModule,
+    MatInputModule,
+    MatTimepickerModule,
+    MatDatepickerModule,
+    FormsModule,
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TimepickerDatepickerIntegrationExample {
+  value: Date;
+}

src/components-examples/material/timepicker/timepicker-forms/timepicker-forms-example.html

@@ -0,0 +1,10 @@
+<mat-form-field>
+  <mat-label>Pick a time</mat-label>
+  <input matInput [formControl]="formControl" [matTimepicker]="picker">
+  <mat-timepicker-toggle matIconSuffix [for]="picker"/>
+  <mat-timepicker #picker/>
+</mat-form-field>
+
+<p>Value: {{formControl.value}}</p>
+<p>Touched: {{formControl.touched}}</p>
+<p>Dirty: {{formControl.dirty}}</p>

src/components-examples/material/timepicker/timepicker-forms/timepicker-forms-example.ts

@@ -0,0 +1,24 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {FormControl, ReactiveFormsModule} from '@angular/forms';
+import {MatTimepickerModule} from '@angular/material/timepicker';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {provideNativeDateAdapter} from '@angular/material/core';
+
+/** @title Timepicker forms integration */
+@Component({
+  selector: 'timepicker-forms-example',
+  templateUrl: 'timepicker-forms-example.html',
+  providers: [provideNativeDateAdapter()],
+  imports: [MatFormFieldModule, MatInputModule, MatTimepickerModule, ReactiveFormsModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TimepickerFormsExample {
+  formControl: FormControl<Date | null>;
+
+  constructor() {
+    const initialValue = new Date();
+    initialValue.setHours(12, 30, 0);
+    this.formControl = new FormControl(initialValue);
+  }
+}

src/components-examples/material/timepicker/timepicker-locale/timepicker-locale-example.html

@@ -0,0 +1,8 @@
+<mat-form-field>
+  <mat-label>Pick a time</mat-label>
+  <input matInput [(ngModel)]="value" [matTimepicker]="picker">
+  <mat-timepicker-toggle matIconSuffix [for]="picker"/>
+  <mat-timepicker #picker/>
+</mat-form-field>
+
+<button mat-button (click)="switchLocale()">Dynamically switch to Bulgarian</button>

src/components-examples/material/timepicker/timepicker-locale/timepicker-locale-example.ts

@@ -0,0 +1,24 @@
+import {ChangeDetectionStrategy, Component, inject} from '@angular/core';
+import {FormsModule} from '@angular/forms';
+import {MatTimepickerModule} from '@angular/material/timepicker';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {DateAdapter, provideNativeDateAdapter} from '@angular/material/core';
+import {MatButtonModule} from '@angular/material/button';
+
+/** @title Timepicker with different locale */
+@Component({
+  selector: 'timepicker-locale-example',
+  templateUrl: 'timepicker-locale-example.html',
+  providers: [provideNativeDateAdapter()],
+  imports: [MatFormFieldModule, MatInputModule, MatTimepickerModule, FormsModule, MatButtonModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TimepickerLocaleExample {
+  private readonly _adapter = inject<DateAdapter<unknown, unknown>>(DateAdapter);
+  value = new Date(2024, 0, 1, 13, 45, 0);
+
+  protected switchLocale() {
+    this._adapter.setLocale('bg-BG');
+  }
+}

src/components-examples/material/timepicker/timepicker-options/timepicker-options-example.html

@@ -0,0 +1,30 @@
+<h3>Interval examples</h3>
+
+<div>
+  <mat-form-field>
+    <mat-label>Every 45 minutes</mat-label>
+    <input matInput [matTimepicker]="minutesPicker">
+    <mat-timepicker-toggle matIconSuffix [for]="minutesPicker"/>
+    <mat-timepicker interval="45min" #minutesPicker/>
+  </mat-form-field>
+</div>
+
+<div>
+  <mat-form-field>
+    <mat-label>Every 3.5 hours</mat-label>
+    <input matInput [matTimepicker]="hoursPicker">
+    <mat-timepicker-toggle matIconSuffix [for]="hoursPicker"/>
+    <mat-timepicker interval="3.5h" #hoursPicker/>
+  </mat-form-field>
+</div>
+
+<h3>Custom list of options</h3>
+
+<div>
+  <mat-form-field>
+    <mat-label>Pick a time of day</mat-label>
+    <input matInput [matTimepicker]="customPicker">
+    <mat-timepicker-toggle matIconSuffix [for]="customPicker"/>
+    <mat-timepicker [options]="customOptions" #customPicker/>
+  </mat-form-field>
+</div>

src/components-examples/material/timepicker/timepicker-options/timepicker-options-example.ts

@@ -0,0 +1,21 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {MatTimepickerModule, MatTimepickerOption} from '@angular/material/timepicker';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {provideNativeDateAdapter} from '@angular/material/core';
+
+/** @title Timepicker options customization */
+@Component({
+  selector: 'timepicker-options-example',
+  templateUrl: 'timepicker-options-example.html',
+  providers: [provideNativeDateAdapter()],
+  imports: [MatFormFieldModule, MatInputModule, MatTimepickerModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TimepickerOptionsExample {
+  customOptions: MatTimepickerOption<Date>[] = [
+    {label: 'Morning', value: new Date(2024, 0, 1, 9, 0, 0)},
+    {label: 'Noon', value: new Date(2024, 0, 1, 12, 0, 0)},
+    {label: 'Evening', value: new Date(2024, 0, 1, 22, 0, 0)},
+  ];
+}

src/components-examples/material/timepicker/timepicker-overview/timepicker-overview-example.html

@@ -1,6 +1,8 @@
 <mat-form-field>
   <mat-label>Pick a time</mat-label>
+<!-- #docregion minimum-setup -->
   <input matInput [matTimepicker]="picker">
   <mat-timepicker-toggle matIconSuffix [for]="picker"/>
   <mat-timepicker #picker/>
+<!-- #enddocregion minimum-setup -->
 </mat-form-field>

src/components-examples/material/timepicker/timepicker-validation/timepicker-validation-example.css

@@ -0,0 +1,3 @@
+mat-form-field {
+  margin-bottom: 30px;
+}

src/components-examples/material/timepicker/timepicker-validation/timepicker-validation-example.html

@@ -0,0 +1,26 @@
+<mat-form-field>
+  <mat-label>Pick a time</mat-label>
+  <input
+    matInput
+    [formControl]="formControl"
+    [matTimepicker]="picker"
+    matTimepickerMin="12:30"
+    matTimepickerMax="17:30">
+  <mat-timepicker-toggle matIconSuffix [for]="picker"/>
+  <mat-timepicker #picker/>
+
+  @if (formControl.errors?.['matTimepickerParse']) {
+    <mat-error>Value isn't a valid time</mat-error>
+  }
+
+  @if (formControl.errors?.['matTimepickerMin']) {
+    <mat-error>Value is too early</mat-error>
+  }
+
+  @if (formControl.errors?.['matTimepickerMax']) {
+    <mat-error>Value is too late</mat-error>
+  }
+</mat-form-field>
+
+<p>Enter a value before 12:30 PM or after 5:30 PM to see the errors</p>
+<p>Errors: {{formControl.errors | json}}</p>

src/components-examples/material/timepicker/timepicker-validation/timepicker-validation-example.ts

@@ -0,0 +1,20 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {JsonPipe} from '@angular/common';
+import {FormControl, ReactiveFormsModule} from '@angular/forms';
+import {MatTimepickerModule} from '@angular/material/timepicker';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {provideNativeDateAdapter} from '@angular/material/core';
+
+/** @title Timepicker validation */
+@Component({
+  selector: 'timepicker-validation-example',
+  templateUrl: 'timepicker-validation-example.html',
+  styleUrl: './timepicker-validation-example.css',
+  providers: [provideNativeDateAdapter()],
+  imports: [MatFormFieldModule, MatInputModule, MatTimepickerModule, ReactiveFormsModule, JsonPipe],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TimepickerValidationExample {
+  formControl = new FormControl<Date | null>(null);
+}