From 8edb840441a4333e09a26d52a1befc6d0342a2ba Mon Sep 17 00:00:00 2001
From: Eric Kidder <eric@kidderberg.us>
Date: Wed, 7 May 2025 18:54:20 -0400
Subject: [PATCH] feat:(angular/component): Configurable reversion value for
 requireSelection for MatAutocomplete

Adds a new input for `MatAutocomplete`: `revertValueTo`. This input works with `requireSelection`
and allows the developer to provide a value that should be reverted to _instead_ of `null`. One
use case for this feature is to have the autocomplete revert to the _last known_ value instead
of `null` with something like: `[revertValueTo]="formControl.value"`

This defaults to `null` in order to maintain backwards compatibility.

The use-case that led to this change is a time zone picker. If the user does not select a time
zone, it will revert to either the previously selected time zone or the browser's time zone.

Video using the demo app: https://www.youtube.com/watch?v=cqZ2WzNDZbk
---
 .../autocomplete-revert-to-value-example.css  | 10 ++
 .../autocomplete-revert-to-value-example.html | 20 ++++
 .../autocomplete-revert-to-value-example.ts   | 36 ++++++++
 .../material/autocomplete/index.ts            |  1 +
 src/dev-app/autocomplete/BUILD.bazel          |  1 +
 .../autocomplete/autocomplete-demo.html       | 33 ++++++-
 src/dev-app/autocomplete/autocomplete-demo.ts |  5 +
 .../autocomplete/autocomplete-trigger.ts      |  9 +-
 src/material/autocomplete/autocomplete.md     | 13 +++
 .../autocomplete/autocomplete.spec.ts         | 91 +++++++++++++++++++
 src/material/autocomplete/autocomplete.ts     | 12 +++
 11 files changed, 227 insertions(+), 4 deletions(-)
 create mode 100644 src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.css
 create mode 100644 src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.html
 create mode 100644 src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.ts

diff --git a/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.css b/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.css
new file mode 100644
index 000000000000..951aee759961
--- /dev/null
+++ b/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.css
@@ -0,0 +1,10 @@
+.example-form {
+  min-width: 150px;
+  max-width: 500px;
+  width: 100%;
+  margin-top: 16px;
+}
+
+.example-full-width {
+  width: 100%;
+}
diff --git a/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.html b/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.html
new file mode 100644
index 000000000000..c40d79faf328
--- /dev/null
+++ b/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.html
@@ -0,0 +1,20 @@
+Control value: {{myControl.value || 'empty'}}
+
+<form class="example-form">
+  <mat-form-field class="example-full-width">
+    <mat-label>Number</mat-label>
+    <input #input
+           type="text"
+           placeholder="Pick one"
+           matInput
+           [formControl]="myControl"
+           [matAutocomplete]="auto"
+           (input)="filter()"
+           (focus)="filter()">
+    <mat-autocomplete requireSelection #auto="matAutocomplete" revertToValue="Three">
+      @for (option of filteredOptions; track option) {
+        <mat-option [value]="option">{{option}}</mat-option>
+      }
+    </mat-autocomplete>
+  </mat-form-field>
+</form>
diff --git a/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.ts b/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.ts
new file mode 100644
index 000000000000..4b3d3bb384df
--- /dev/null
+++ b/src/components-examples/material/autocomplete/autocomplete-revert-to-value/autocomplete-revert-to-value-example.ts
@@ -0,0 +1,36 @@
+import {Component, ElementRef, ViewChild} from '@angular/core';
+import {FormControl, FormsModule, ReactiveFormsModule} from '@angular/forms';
+import {MatAutocompleteModule} from '@angular/material/autocomplete';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+
+/**
+ * @title Revert to a given value instead of null for requireSelection
+ */
+@Component({
+  selector: 'autocomplete-revert-to-value-example',
+  templateUrl: 'autocomplete-revert-to-value-example.html',
+  styleUrl: 'autocomplete-revert-to-value-example.css',
+  imports: [
+    FormsModule,
+    MatFormFieldModule,
+    MatInputModule,
+    MatAutocompleteModule,
+    ReactiveFormsModule,
+  ],
+})
+export class AutocompleteRevertToValueExample {
+  @ViewChild('input') input: ElementRef<HTMLInputElement>;
+  myControl = new FormControl('');
+  options: string[] = ['One', 'Two', 'Three', 'Four', 'Five'];
+  filteredOptions: string[];
+
+  constructor() {
+    this.filteredOptions = this.options.slice();
+  }
+
+  filter(): void {
+    const filterValue = this.input.nativeElement.value.toLowerCase();
+    this.filteredOptions = this.options.filter(o => o.toLowerCase().includes(filterValue));
+  }
+}
diff --git a/src/components-examples/material/autocomplete/index.ts b/src/components-examples/material/autocomplete/index.ts
index 18aad314a477..a558e6aeedc0 100644
--- a/src/components-examples/material/autocomplete/index.ts
+++ b/src/components-examples/material/autocomplete/index.ts
@@ -6,4 +6,5 @@ export {AutocompleteOverviewExample} from './autocomplete-overview/autocomplete-
 export {AutocompletePlainInputExample} from './autocomplete-plain-input/autocomplete-plain-input-example';
 export {AutocompleteSimpleExample} from './autocomplete-simple/autocomplete-simple-example';
 export {AutocompleteRequireSelectionExample} from './autocomplete-require-selection/autocomplete-require-selection-example';
+export {AutocompleteRevertToValueExample} from './autocomplete-revert-to-value/autocomplete-revert-to-value-example';
 export {AutocompleteHarnessExample} from './autocomplete-harness/autocomplete-harness-example';
diff --git a/src/dev-app/autocomplete/BUILD.bazel b/src/dev-app/autocomplete/BUILD.bazel
index 8ed724206443..64ce915e9dae 100644
--- a/src/dev-app/autocomplete/BUILD.bazel
+++ b/src/dev-app/autocomplete/BUILD.bazel
@@ -20,6 +20,7 @@ ng_project(
         "//src/material/dialog",
         "//src/material/form-field",
         "//src/material/input",
+        "//src/material/select",
     ],
 )
 
diff --git a/src/dev-app/autocomplete/autocomplete-demo.html b/src/dev-app/autocomplete/autocomplete-demo.html
index 401f1180e4ae..d7b8ac8e15f1 100644
--- a/src/dev-app/autocomplete/autocomplete-demo.html
+++ b/src/dev-app/autocomplete/autocomplete-demo.html
@@ -20,7 +20,8 @@
       [displayWith]="displayFn"
       [hideSingleSelectionIndicator]="reactiveHideSingleSelectionIndicator"
       [autoActiveFirstOption]="reactiveAutoActiveFirstOption"
-      [requireSelection]="reactiveRequireSelection">
+      [requireSelection]="reactiveRequireSelection"
+      [revertToValue]="reactiveRevertToValue">
       @for (state of reactiveStates; track state; let index = $index) {
         <mat-option [value]="state" [disabled]="reactiveIsStateDisabled(state.index)">
           <span>{{ state.name }}</span>
@@ -59,6 +60,20 @@
         Require Selection
       </mat-checkbox>
     </p>
+    <p>
+      <mat-form-field>
+        <mat-label>Revert value to</mat-label>
+        <mat-select [(ngModel)]="reactiveRevertToValue" [disabled]="!reactiveRequireSelection">
+          <mat-option [value]="null">None</mat-option>
+            @for (state of states; track state) {
+            <mat-option [value]="state">
+              <span>{{ state.name }}</span>
+              <span class="demo-secondary-text"> ({{ state.code }}) </span>
+            </mat-option>
+          }
+        </mat-select>
+      </mat-form-field>
+    </p>
 
   </mat-card>
 
@@ -76,7 +91,8 @@
         <mat-autocomplete #tdAuto="matAutocomplete"
           [hideSingleSelectionIndicator]="templateHideSingleSelectionIndicator"
           [autoActiveFirstOption]="templateAutoActiveFirstOption"
-          [requireSelection]="templateRequireSelection">
+          [requireSelection]="templateRequireSelection"
+          [revertToValue]="templateRevertToValue">
           @for (state of tdStates; track state) {
             <mat-option [value]="state.name"
               [disabled]="templateIsStateDisabled(state.index)">
@@ -113,6 +129,19 @@
         Require Selection
       </mat-checkbox>
     </p>
+    <p>
+      <mat-form-field>
+        <mat-label>Revert value to</mat-label>
+        <mat-select [(ngModel)]="templateRevertToValue" [disabled]="!templateRequireSelection">
+          <mat-option [value]="null">None</mat-option>
+            @for (state of states; track state) {
+            <mat-option [value]="state.name">
+              <span>{{ state.name }}</span>
+            </mat-option>
+          }
+        </mat-select>
+      </mat-form-field>
+    </p>
     <p>
       <label for="template-disable-state-options">Disable States</label>
       <select [(ngModel)]="templateDisableStateOption" id="template-disable-state-options">
diff --git a/src/dev-app/autocomplete/autocomplete-demo.ts b/src/dev-app/autocomplete/autocomplete-demo.ts
index 408217b7679e..9c4ed53f5dcb 100644
--- a/src/dev-app/autocomplete/autocomplete-demo.ts
+++ b/src/dev-app/autocomplete/autocomplete-demo.ts
@@ -13,6 +13,7 @@ import {MatAutocompleteModule} from '@angular/material/autocomplete';
 import {MatButtonModule} from '@angular/material/button';
 import {MatCardModule} from '@angular/material/card';
 import {MatCheckboxModule} from '@angular/material/checkbox';
+import {MatSelectModule} from '@angular/material/select';
 import {ThemePalette} from '@angular/material/core';
 import {MatDialog, MatDialogRef} from '@angular/material/dialog';
 import {MatInputModule} from '@angular/material/input';
@@ -42,6 +43,7 @@ type DisableStateOption = 'none' | 'first-middle-last' | 'all';
     MatCardModule,
     MatCheckboxModule,
     MatInputModule,
+    MatSelectModule,
     ReactiveFormsModule,
   ],
   changeDetection: ChangeDetectionStrategy.OnPush,
@@ -68,6 +70,9 @@ export class AutocompleteDemo {
   reactiveRequireSelection = false;
   templateRequireSelection = false;
 
+  reactiveRevertToValue = null;
+  templateRevertToValue = null;
+
   reactiveHideSingleSelectionIndicator = false;
   templateHideSingleSelectionIndicator = false;
 
diff --git a/src/material/autocomplete/autocomplete-trigger.ts b/src/material/autocomplete/autocomplete-trigger.ts
index 7ddf9fc79ef4..d6b6741ae9da 100644
--- a/src/material/autocomplete/autocomplete-trigger.ts
+++ b/src/material/autocomplete/autocomplete-trigger.ts
@@ -757,8 +757,13 @@ export class MatAutocompleteTrigger
       this._element.nativeElement.value !== this._valueOnAttach
     ) {
       this._clearPreviousSelectedOption(null);
-      this._assignOptionValue(null);
-      this._onChange(null);
+      if (panel.revertToValue) {
+        this._assignOptionValue(panel.revertToValue);
+        this._onChange(panel.revertToValue);
+      } else {
+        this._assignOptionValue(null);
+        this._onChange(null);
+      }
     }
 
     this.closePanel();
diff --git a/src/material/autocomplete/autocomplete.md b/src/material/autocomplete/autocomplete.md
index 12306f3f9b7d..07f6d6225b39 100644
--- a/src/material/autocomplete/autocomplete.md
+++ b/src/material/autocomplete/autocomplete.md
@@ -77,6 +77,19 @@ injection token.
 
 <!-- example(autocomplete-require-selection) -->
 
+### Revert to a given value instead of `null`
+
+Instead of setting the autocomplete value to `null`, the `revertToValue` input can be set to 
+provide a value to be set instead. This is useful in cases where the autocomplete should change
+to a previously known value or default value if nothing is selected, instead of `null`.
+
+Because the value may not present in the filtered options, this does _not_ trigger the
+`selectionChange` event. However, for both reactive and template form controls, the value will
+be updated appropriately. This does mean that it is possible to set the value to something that
+is not present in the options list.
+
+<!-- example(autocomplete-revert-to-value) -->
+
 ### Automatically highlighting the first option
 
 If your use case requires for the first autocomplete option to be highlighted when the user opens
diff --git a/src/material/autocomplete/autocomplete.spec.ts b/src/material/autocomplete/autocomplete.spec.ts
index 5284c4ff922d..3d22fe02f4c7 100644
--- a/src/material/autocomplete/autocomplete.spec.ts
+++ b/src/material/autocomplete/autocomplete.spec.ts
@@ -2859,6 +2859,95 @@ describe('MatAutocomplete', () => {
       expect(input.value).toBe('');
       expect(stateCtrl.value).toBe(null);
     }));
+
+    it('should revert to the provided value if requireSelection is enabled and revertToValue is provided', waitForAsync(async () => {
+      const input = fixture.nativeElement.querySelector('input');
+      const {stateCtrl, trigger} = fixture.componentInstance;
+      fixture.componentInstance.requireSelection = true;
+      fixture.componentInstance.revertToValue = {code: 'DE', name: 'Delaware'};
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      await new Promise(r => setTimeout(r));
+
+      // Simulate opening the input and clicking the first option.
+      trigger.openPanel();
+      fixture.detectChanges();
+      await new Promise(r => setTimeout(r));
+      (overlayContainerElement.querySelector('mat-option') as HTMLElement).click();
+      await new Promise(r => setTimeout(r));
+      fixture.detectChanges();
+
+      expect(trigger.panelOpen).toBe(false);
+      expect(input.value).toBe('Alabama');
+      expect(stateCtrl.value).toEqual({code: 'AL', name: 'Alabama'});
+
+      // Simulate pressing backspace while focus is still on the input.
+      dispatchFakeEvent(input, 'keydown');
+      input.value = 'Alabam';
+      fixture.detectChanges();
+      dispatchFakeEvent(input, 'input');
+      fixture.detectChanges();
+      await new Promise(r => setTimeout(r));
+
+      expect(trigger.panelOpen).toBe(true);
+      expect(input.value).toBe('Alabam');
+      expect(stateCtrl.value).toEqual({code: 'AL', name: 'Alabama'});
+
+      // Simulate clicking away.
+      input.blur();
+      dispatchFakeEvent(document, 'click');
+      fixture.detectChanges();
+      await new Promise(r => setTimeout(r));
+
+      expect(trigger.panelOpen).toBe(false);
+      expect(input.value).toBe('Delaware');
+      expect(stateCtrl.value).toEqual({code: 'DE', name: 'Delaware'});
+    }));
+
+    it('should keep the input value if requireSelection is disabled and revertToValue is provided', waitForAsync(async () => {
+      const input = fixture.nativeElement.querySelector('input');
+      const {stateCtrl, trigger} = fixture.componentInstance;
+      fixture.componentInstance.requireSelection = false;
+      fixture.componentInstance.revertToValue = {code: 'DE', name: 'Delaware'};
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+      await new Promise(r => setTimeout(r));
+
+      // Simulate opening the input and clicking the first option.
+      trigger.openPanel();
+      fixture.detectChanges();
+      await new Promise(r => setTimeout(r));
+      (overlayContainerElement.querySelector('mat-option') as HTMLElement).click();
+      await new Promise(r => setTimeout(r));
+      fixture.detectChanges();
+
+      expect(trigger.panelOpen).toBe(false);
+      expect(input.value).toBe('Alabama');
+      expect(stateCtrl.value).toEqual({code: 'AL', name: 'Alabama'});
+
+      // Simulate pressing backspace while focus is still on the input.
+      dispatchFakeEvent(input, 'keydown');
+      input.value = 'Alabam';
+      fixture.detectChanges();
+      dispatchFakeEvent(input, 'input');
+      fixture.detectChanges();
+      await new Promise(r => setTimeout(r));
+
+      expect(trigger.panelOpen).toBe(true);
+      expect(input.value).toBe('Alabam');
+      expect(stateCtrl.value).toEqual('Alabam');
+
+      // Simulate clicking away.
+      input.blur();
+      dispatchFakeEvent(document, 'click');
+      fixture.detectChanges();
+
+      await new Promise(r => setTimeout(r));
+
+      expect(trigger.panelOpen).toBe(false);
+      expect(input.value).toBe('Alabam');
+      expect(stateCtrl.value).toEqual('Alabam');
+    }));
   });
 
   describe('panel closing', () => {
@@ -3997,6 +4086,7 @@ const SIMPLE_AUTOCOMPLETE_TEMPLATE = `
     [displayWith]="displayFn"
     [disableRipple]="disableRipple"
     [requireSelection]="requireSelection"
+    [revertToValue]="revertToValue"
     [aria-label]="ariaLabel"
     [aria-labelledby]="ariaLabelledby"
     (opened)="openedSpy()"
@@ -4033,6 +4123,7 @@ class SimpleAutocomplete implements OnDestroy {
   autocompleteDisabled = false;
   hasLabel = true;
   requireSelection = false;
+  revertToValue: {code: string; name: string; height?: number; disabled?: boolean} | null = null;
   ariaLabel: string;
   ariaLabelledby: string;
   panelClass = 'class-one class-two';
diff --git a/src/material/autocomplete/autocomplete.ts b/src/material/autocomplete/autocomplete.ts
index 54078571d1f0..0be6e9d9abf3 100644
--- a/src/material/autocomplete/autocomplete.ts
+++ b/src/material/autocomplete/autocomplete.ts
@@ -70,6 +70,12 @@ export interface MatAutocompleteDefaultOptions {
    */
   requireSelection?: boolean;
 
+  /**
+   * If requireSelection is true, this input can be used to specify the value to revert to when
+   * the user closes the autocomplete panel without selecting an option. Defaults to null.
+   */
+  revertToValue?: unknown | null;
+
   /** Class to be applied to the autocomplete's backdrop. */
   backdropClass?: string;
 
@@ -192,6 +198,12 @@ export class MatAutocomplete implements AfterContentInit, OnDestroy {
    */
   @Input({transform: booleanAttribute}) requireSelection: boolean;
 
+  /**
+   * If requireSelection is true, this input can be used to specify the value to revert to when
+   * the user closes the autocomplete panel without selecting an option. Defaults to null.
+   */
+  @Input() revertToValue: unknown | null = null;
+
   /**
    * Specify the width of the autocomplete panel.  Can be any CSS sizing value, otherwise it will
    * match the width of its host.