feat(material/timepicker): add option template

close #31209

Author: lekhmanrus

goldens/material/timepicker/index.api.md

@@ -38,7 +38,7 @@ export class MatTimepicker<D> implements OnDestroy, MatOptionParentComponent {
     constructor();
     readonly activeDescendant: Signal<string | null>;
     // (undocumented)
-    protected _animationsDisabled: boolean;
+    protected readonly _animationsDisabled: boolean;
     readonly ariaLabel: InputSignal<string | null>;
     readonly ariaLabelledby: InputSignal<string | null>;
     close(): void;
@@ -55,12 +55,12 @@ export class MatTimepicker<D> implements OnDestroy, MatOptionParentComponent {
     readonly opened: OutputEmitterRef<void>;
     readonly options: InputSignal<readonly MatTimepickerOption<D>[] | null>;
     // (undocumented)
-    protected _options: Signal<readonly MatOption<any>[]>;
+    protected readonly _options: Signal<readonly MatOption<any>[]>;
     // (undocumented)
-    protected _optionTemplate: Signal<TemplateRef<MatTimepickerOption<D>> | undefined>;
+    protected readonly _optionTemplate: Signal<MatTimepickerOptionTemplate<D> | undefined>;
     readonly panelId: string;
     // (undocumented)
-    protected _panelTemplate: Signal<TemplateRef<unknown>>;
+    protected readonly _panelTemplate: Signal<TemplateRef<unknown>>;
     registerInput(input: MatTimepickerConnectedInput<D>): void;
     readonly selected: OutputEmitterRef<MatTimepickerSelected<D>>;
     protected _selectValue(option: MatOption<D>): void;
@@ -131,7 +131,7 @@ export class MatTimepickerModule {
     // (undocumented)
     static ɵinj: i0.ɵɵInjectorDeclaration<MatTimepickerModule>;
     // (undocumented)
-    static ɵmod: i0.ɵɵNgModuleDeclaration<MatTimepickerModule, never, [typeof MatTimepicker, typeof MatTimepickerInput, typeof MatTimepickerToggle], [typeof i1.CdkScrollableModule, typeof MatTimepicker, typeof MatTimepickerInput, typeof MatTimepickerToggle]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<MatTimepickerModule, never, [typeof MatTimepicker, typeof MatTimepickerInput, typeof MatTimepickerOptionTemplate, typeof MatTimepickerToggle], [typeof i1.CdkScrollableModule, typeof MatTimepicker, typeof MatTimepickerInput, typeof MatTimepickerOptionTemplate, typeof MatTimepickerToggle]>;
 }
 
 // @public
@@ -140,6 +140,16 @@ export interface MatTimepickerOption<D = unknown> {
     value: D;
 }
 
+// @public
+export class MatTimepickerOptionTemplate<D> {
+    // (undocumented)
+    readonly template: TemplateRef<MatTimepickerOption<D>>;
+    // (undocumented)
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MatTimepickerOptionTemplate<any>, "ng-template[matTimepickerOption]", never, {}, {}, never, never, true, never>;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<MatTimepickerOptionTemplate<any>, never>;
+}
+
 // @public
 export interface MatTimepickerSelected<D> {
     // (undocumented)

src/components-examples/material/timepicker/timepicker-option-template/timepicker-option-template-example.html

@@ -3,7 +3,7 @@
   <input matInput [matTimepicker]="picker">
   <mat-timepicker-toggle matIconSuffix [for]="picker"/>
   <mat-timepicker #picker>
-    <ng-template let-option>
+    <ng-template matTimepickerOption let-option>
       <mat-icon>
         {{ (dateAdapter.compareTime(option.value, sunrise) > 0 && dateAdapter.compareTime(option.value, sunset) < 0) ? 'sunny' : 'bedtime' }}
       </mat-icon>

src/material/timepicker/BUILD.bazel

@@ -68,6 +68,7 @@ ng_project(
         "timepicker.ts",
         "timepicker-input.ts",
         "timepicker-module.ts",
+        "timepicker-option.ts",
         "timepicker-toggle.ts",
         "util.ts",
     ],

src/material/timepicker/public-api.ts

@@ -8,6 +8,7 @@
 
 export * from './timepicker';
 export * from './timepicker-input';
+export * from './timepicker-option';
 export * from './timepicker-toggle';
 export * from './timepicker-module';
 export {MatTimepickerOption, MAT_TIMEPICKER_CONFIG, MatTimepickerConfig} from './util';

src/material/timepicker/timepicker-module.ts

@@ -10,10 +10,17 @@ import {NgModule} from '@angular/core';
 import {CdkScrollableModule} from '@angular/cdk/scrolling';
 import {MatTimepicker} from './timepicker';
 import {MatTimepickerInput} from './timepicker-input';
+import {MatTimepickerOptionTemplate} from './timepicker-option';
 import {MatTimepickerToggle} from './timepicker-toggle';
 
 @NgModule({
-  imports: [MatTimepicker, MatTimepickerInput, MatTimepickerToggle],
-  exports: [CdkScrollableModule, MatTimepicker, MatTimepickerInput, MatTimepickerToggle],
+  imports: [MatTimepicker, MatTimepickerInput, MatTimepickerOptionTemplate, MatTimepickerToggle],
+  exports: [
+    CdkScrollableModule,
+    MatTimepicker,
+    MatTimepickerInput,
+    MatTimepickerOptionTemplate,
+    MatTimepickerToggle,
+  ],
 })
 export class MatTimepickerModule {}

src/material/timepicker/timepicker-option.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {Directive, TemplateRef, inject} from '@angular/core';
+import {MatTimepickerOption} from './util';
+
+/** Template to be used to override the timepicker's option labels. */
+@Directive({
+  selector: 'ng-template[matTimepickerOption]',
+})
+export class MatTimepickerOptionTemplate<D> {
+  readonly template = inject<TemplateRef<MatTimepickerOption<D>>>(TemplateRef);
+}

src/material/timepicker/timepicker.html

@@ -14,7 +14,7 @@
       <mat-option
         [value]="option.value"
         (onSelectionChange)="_selectValue($event.source)">
-        <ng-container [ngTemplateOutlet]="_optionTemplate() || defaultOptionTemplate"
+        <ng-container [ngTemplateOutlet]="_optionTemplate()?.template || defaultOptionTemplate"
                       [ngTemplateOutletContext]="{ $implicit: option }">
         </ng-container>
       </mat-option>

src/material/timepicker/timepicker.spec.ts

@@ -1,6 +1,13 @@
-import {Component, Injector, Provider, signal, ViewChild, ViewEncapsulation} from '@angular/core';
+import {
+  Component,
+  inject,
+  Injector,
+  Provider,
+  signal,
+  ViewChild,
+  ViewEncapsulation,
+} from '@angular/core';
 import {ComponentFixture, fakeAsync, flush, TestBed} from '@angular/core/testing';
-import {DateAdapter, MATERIAL_ANIMATIONS, provideNativeDateAdapter} from '../core';
 import {
   clearElement,
   dispatchFakeEvent,
@@ -20,16 +27,18 @@ import {
   TAB,
   UP_ARROW,
 } from '@angular/cdk/keycodes';
-import {MatInput} from '../input';
+import {createCloseScrollStrategy} from '@angular/cdk/overlay';
+import {ScrollDispatcher} from '@angular/cdk/scrolling';
+import {FormControl, ReactiveFormsModule, Validators} from '@angular/forms';
+import {Subject} from 'rxjs';
+import {DateAdapter, MATERIAL_ANIMATIONS, provideNativeDateAdapter} from '../core';
 import {MatFormField, MatLabel, MatSuffix} from '../form-field';
+import {MatInput} from '../input';
 import {MatTimepickerInput} from './timepicker-input';
-import {MAT_TIMEPICKER_SCROLL_STRATEGY, MatTimepicker} from './timepicker';
+import {MatTimepickerOptionTemplate} from './timepicker-option';
 import {MatTimepickerToggle} from './timepicker-toggle';
+import {MAT_TIMEPICKER_SCROLL_STRATEGY, MatTimepicker} from './timepicker';
 import {MAT_TIMEPICKER_CONFIG, MatTimepickerOption} from './util';
-import {FormControl, ReactiveFormsModule, Validators} from '@angular/forms';
-import {ScrollDispatcher} from '@angular/cdk/scrolling';
-import {createCloseScrollStrategy} from '@angular/cdk/overlay';
-import {Subject} from 'rxjs';
 
 describe('MatTimepicker', () => {
   let adapter: DateAdapter<Date>;
@@ -652,6 +661,24 @@ describe('MatTimepicker', () => {
       fixture.detectChanges();
       expect(fixture.componentInstance.timepicker.interval()).toBe(null);
     });
+
+    it('should be able to apply custom options template', () => {
+      const fixture = TestBed.createComponent(TimepickerOptionTemplate);
+      fixture.detectChanges();
+
+      getInput(fixture).click();
+      fixture.detectChanges();
+      expect(getOptions().map(o => o.textContent.trim())).toEqual([
+        '12:00 AM (off-hours)',
+        '3:00 AM (off-hours)',
+        '6:00 AM (off-hours)',
+        '9:00 AM (working hours)',
+        '12:00 PM (working hours)',
+        '3:00 PM (working hours)',
+        '6:00 PM (off-hours)',
+        '9:00 PM (off-hours)',
+      ]);
+    });
   });
 
   describe('mat-form-field integration', () => {
@@ -1512,3 +1539,28 @@ class TimepickerWithoutInput {
   encapsulation: ViewEncapsulation.ShadowDom,
 })
 class TimepickerInShadowDom {}
+
+@Component({
+  template: `
+    <input [matTimepicker]="picker" />
+    <mat-timepicker #picker interval="3h">
+      <ng-template matTimepickerOption let-option>
+        {{ option.label }}
+        {{ (dateAdapter.compareTime(option.value, workStartTime) > 0 && dateAdapter.compareTime(option.value, workEndTime) < 0) ? '(working hours)' : '(off-hours)' }}
+      </ng-template>
+    </mat-timepicker>
+  `,
+  imports: [MatTimepicker, MatTimepickerInput, MatTimepickerOptionTemplate],
+})
+class TimepickerOptionTemplate {
+  readonly dateAdapter = inject<DateAdapter<Date>>(DateAdapter);
+  readonly workStartTime: Date;
+  readonly workEndTime: Date;
+
+  constructor() {
+    this.workStartTime = new Date();
+    this.workStartTime.setHours(8, 30, 0);
+    this.workEndTime = new Date();
+    this.workEndTime.setHours(17, 0, 0);
+  }
+}

src/material/timepicker/timepicker.ts

@@ -20,11 +20,9 @@ import {
   InjectionToken,
   Injector,
   input,
-  InputSignal,
   InputSignalWithTransform,
   OnDestroy,
   output,
-  OutputEmitterRef,
   Signal,
   signal,
   TemplateRef,
@@ -55,14 +53,15 @@ import {TemplatePortal} from '@angular/cdk/portal';
 import {_getEventTarget} from '@angular/cdk/platform';
 import {ENTER, ESCAPE, hasModifierKey, TAB} from '@angular/cdk/keycodes';
 import {_IdGenerator, ActiveDescendantKeyManager} from '@angular/cdk/a11y';
+import {Subscription} from 'rxjs';
 import {
   generateOptions,
   MAT_TIMEPICKER_CONFIG,
   MatTimepickerOption,
   parseInterval,
   validateAdapter,
 } from './util';
-import {Subscription} from 'rxjs';
+import {MatTimepickerOptionTemplate} from './timepicker-option';
 
 /** Event emitted when a value is selected in the timepicker. */
 export interface MatTimepickerSelected<D> {
@@ -129,31 +128,33 @@ export interface MatTimepickerConnectedInput<D> {
   ],
 })
 export class MatTimepicker<D> implements OnDestroy, MatOptionParentComponent {
-  private _dir = inject(Directionality, {optional: true});
-  private _viewContainerRef = inject(ViewContainerRef);
-  private _injector = inject(Injector);
-  private _defaultConfig = inject(MAT_TIMEPICKER_CONFIG, {optional: true});
-  private _dateAdapter = inject<DateAdapter<D>>(DateAdapter, {optional: true})!;
-  private _dateFormats = inject(MAT_DATE_FORMATS, {optional: true})!;
-  private _scrollStrategyFactory = inject(MAT_TIMEPICKER_SCROLL_STRATEGY);
-  protected _animationsDisabled = _animationsDisabled();
-
-  private _isOpen = signal(false);
-  private _activeDescendant = signal<string | null>(null);
-
-  private _input = signal<MatTimepickerConnectedInput<D> | null>(null);
+  private readonly _dir = inject(Directionality, {optional: true});
+  private readonly _viewContainerRef = inject(ViewContainerRef);
+  private readonly _injector = inject(Injector);
+  private readonly _defaultConfig = inject(MAT_TIMEPICKER_CONFIG, {optional: true});
+  private readonly _dateAdapter = inject<DateAdapter<D>>(DateAdapter, {optional: true})!;
+  private readonly _dateFormats = inject(MAT_DATE_FORMATS, {optional: true})!;
+  private readonly _scrollStrategyFactory = inject(MAT_TIMEPICKER_SCROLL_STRATEGY);
+  protected readonly _animationsDisabled = _animationsDisabled();
+
+  private readonly _isOpen = signal(false);
+  private readonly _activeDescendant = signal<string | null>(null);
+
+  private readonly _input = signal<MatTimepickerConnectedInput<D> | null>(null);
   private _overlayRef: OverlayRef | null = null;
   private _portal: TemplatePortal<unknown> | null = null;
   private _optionsCacheKey: string | null = null;
   private _localeChanges: Subscription;
   private _onOpenRender: AfterRenderRef | null = null;
 
-  protected _panelTemplate = viewChild.required<TemplateRef<unknown>>('panelTemplate');
   protected _timeOptions: readonly MatTimepickerOption<D>[] = [];
-  protected _options = viewChildren(MatOption);
-  protected _optionTemplate = contentChild<TemplateRef<MatTimepickerOption<D>>>(TemplateRef);
+  protected readonly _panelTemplate = viewChild.required<TemplateRef<unknown>>('panelTemplate');
+  protected readonly _options = viewChildren(MatOption);
+  protected readonly _optionTemplate = contentChild<MatTimepickerOptionTemplate<D>>(
+    MatTimepickerOptionTemplate,
+  );
 
-  private _keyManager = new ActiveDescendantKeyManager(this._options, this._injector)
+  private readonly _keyManager = new ActiveDescendantKeyManager(this._options, this._injector)
     .withHomeAndEnd(true)
     .withPageUpDown(true)
     .withVerticalOrientation(true);
@@ -172,48 +173,43 @@ export class MatTimepicker<D> implements OnDestroy, MatOptionParentComponent {
    * Array of pre-defined options that the user can select from, as an alternative to using the
    * `interval` input. An error will be thrown if both `options` and `interval` are specified.
    */
-  readonly options: InputSignal<readonly MatTimepickerOption<D>[] | null> = input<
-    readonly MatTimepickerOption<D>[] | null
-  >(null);
+  readonly options = input<readonly MatTimepickerOption<D>[] | null>(null);
 
   /** Whether the timepicker is open. */
-  readonly isOpen: Signal<boolean> = this._isOpen.asReadonly();
+  readonly isOpen = this._isOpen.asReadonly();
 
   /** Emits when the user selects a time. */
-  readonly selected: OutputEmitterRef<MatTimepickerSelected<D>> = output();
+  readonly selected = output<MatTimepickerSelected<D>>();
 
   /** Emits when the timepicker is opened. */
-  readonly opened: OutputEmitterRef<void> = output();
+  readonly opened = output();
 
   /** Emits when the timepicker is closed. */
-  readonly closed: OutputEmitterRef<void> = output();
+  readonly closed = output();
 
   /** ID of the active descendant option. */
-  readonly activeDescendant: Signal<string | null> = this._activeDescendant.asReadonly();
+  readonly activeDescendant = this._activeDescendant.asReadonly();
 
   /** Unique ID of the timepicker's panel */
-  readonly panelId: string = inject(_IdGenerator).getId('mat-timepicker-panel-');
+  readonly panelId = inject(_IdGenerator).getId('mat-timepicker-panel-');
 
   /** Whether ripples within the timepicker should be disabled. */
-  readonly disableRipple: InputSignalWithTransform<boolean, unknown> = input(
-    this._defaultConfig?.disableRipple ?? false,
-    {
-      transform: booleanAttribute,
-    },
-  );
+  readonly disableRipple = input(this._defaultConfig?.disableRipple ?? false, {
+    transform: booleanAttribute,
+  });
 
   /** ARIA label for the timepicker panel. */
-  readonly ariaLabel: InputSignal<string | null> = input<string | null>(null, {
+  readonly ariaLabel = input<string | null>(null, {
     alias: 'aria-label',
   });
 
   /** ID of the label element for the timepicker panel. */
-  readonly ariaLabelledby: InputSignal<string | null> = input<string | null>(null, {
+  readonly ariaLabelledby = input<string | null>(null, {
     alias: 'aria-labelledby',
   });
 
   /** Whether the timepicker is currently disabled. */
-  readonly disabled: Signal<boolean> = computed(() => !!this._input()?.disabled());
+  readonly disabled = computed(() => !!this._input()?.disabled());
 
   constructor() {
     if (typeof ngDevMode === 'undefined' || ngDevMode) {