refactor: allow options to be passed to focus methods

Updates the `focus` methods on the different components to allow for the `FocusOptions` to be passed in.

Fixes #14182.

Author: crisbeto

src/material/button-toggle/button-toggle.ts

@@ -519,8 +519,8 @@ export class MatButtonToggle extends _MatButtonToggleMixinBase implements OnInit
   }
 
   /** Focuses the button. */
-  focus(): void {
-    this._buttonElement.nativeElement.focus();
+  focus(options?: FocusOptions): void {
+    this._buttonElement.nativeElement.focus(options);
   }
 
   /** Checks the button toggle due to an interaction with the underlying native button. */

src/material/button/button.ts

@@ -114,8 +114,8 @@ export class MatButton extends _MatButtonMixinBase
   }
 
   /** Focuses the button. */
-  focus(): void {
-    this._getHostElement().focus();
+  focus(options?: FocusOptions): void {
+    this._getHostElement().focus(options);
   }
 
   _getHostElement() {

src/material/checkbox/checkbox.ts

@@ -401,8 +401,8 @@ export class MatCheckbox extends _MatCheckboxMixinBase implements ControlValueAc
   }
 
   /** Focuses the checkbox. */
-  focus(): void {
-    this._focusMonitor.focusVia(this._inputElement, 'keyboard');
+  focus(options?: FocusOptions): void {
+    this._focusMonitor.focusVia(this._inputElement, 'keyboard', options);
   }
 
   _onInteractionEvent(event: Event) {

src/material/chips/chip-input.ts

@@ -156,8 +156,8 @@ export class MatChipInput implements MatChipTextControl, OnChanges {
   }
 
   /** Focuses the input. */
-  focus(): void {
-    this._inputElement.focus();
+  focus(options?: FocusOptions): void {
+    this._inputElement.focus(options);
   }
 
   /** Checks whether a keycode is one of the configured separators. */

src/material/chips/chip-list.ts

@@ -460,7 +460,7 @@ export class MatChipList extends _MatChipListMixinBase implements MatFormFieldCo
    * Focuses the first non-disabled chip in this chip list, or the associated input when there
    * are no eligible chips.
    */
-  focus(): void {
+  focus(options?: FocusOptions): void {
     if (this.disabled) {
       return;
     }
@@ -473,15 +473,15 @@ export class MatChipList extends _MatChipListMixinBase implements MatFormFieldCo
       this._keyManager.setFirstItemActive();
       this.stateChanges.next();
     } else {
-      this._focusInput();
+      this._focusInput(options);
       this.stateChanges.next();
     }
   }
 
   /** Attempt to focus an input if we have one. */
-  _focusInput() {
+  _focusInput(options?: FocusOptions) {
     if (this._chipInput) {
-      this._chipInput.focus();
+      this._chipInput.focus(options);
     }
   }
 

src/material/chips/chip-text-control.ts

@@ -22,5 +22,5 @@ export interface MatChipTextControl {
   empty: boolean;
 
   /** Focuses the text control. */
-  focus(): void;
+  focus(options?: FocusOptions): void;
 }

src/material/core/option/option.ts

@@ -24,6 +24,7 @@ import {
   QueryList,
   ViewEncapsulation,
 } from '@angular/core';
+import {FocusOptions, FocusableOption, FocusOrigin} from '@angular/cdk/a11y';
 import {Subject} from 'rxjs';
 import {MatOptgroup} from './optgroup';
 
@@ -84,7 +85,7 @@ export const MAT_OPTION_PARENT_COMPONENT =
   encapsulation: ViewEncapsulation.None,
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
-export class MatOption implements AfterViewChecked, OnDestroy {
+export class MatOption implements FocusableOption, AfterViewChecked, OnDestroy {
   private _selected = false;
   private _active = false;
   private _disabled = false;
@@ -161,11 +162,13 @@ export class MatOption implements AfterViewChecked, OnDestroy {
   }
 
   /** Sets focus onto this option. */
-  focus(): void {
+  focus(_origin?: FocusOrigin, options?: FocusOptions): void {
+    // Note that we aren't using `_origin`, but we need to keep it because some internal consumers
+    // use `MatOption` in a `FocusKeyManager` and we need it to match `FocusableOption`.
     const element = this._getHostElement();
 
     if (typeof element.focus === 'function') {
-      element.focus();
+      element.focus(options);
     }
   }
 

src/material/expansion/expansion-panel-header.ts

@@ -203,8 +203,8 @@ export class MatExpansionPanelHeader implements OnDestroy, FocusableOption {
    * @param origin Origin of the action that triggered the focus.
    * @docs-private
    */
-  focus(origin: FocusOrigin = 'program') {
-    this._focusMonitor.focusVia(this._element, origin);
+  focus(origin: FocusOrigin = 'program', options?: FocusOptions) {
+    this._focusMonitor.focusVia(this._element, origin, options);
   }
 
   ngOnDestroy() {

src/material/input/input.ts

@@ -310,8 +310,8 @@ export class MatInput extends _MatInputMixinBase implements MatFormFieldControl<
   }
 
   /** Focuses the input. */
-  focus(): void {
-    this._elementRef.nativeElement.focus();
+  focus(options?: FocusOptions): void {
+    this._elementRef.nativeElement.focus(options);
   }
 
   /** Callback for the cases where the focused state of the input changes. */

src/material/list/selection-list.ts

@@ -320,8 +320,8 @@ export class MatListOption extends _MatListOptionMixinBase
   providers: [MAT_SELECTION_LIST_VALUE_ACCESSOR],
   changeDetection: ChangeDetectionStrategy.OnPush
 })
-export class MatSelectionList extends _MatSelectionListMixinBase implements FocusableOption,
-    CanDisableRipple, AfterContentInit, ControlValueAccessor, OnDestroy, OnChanges {
+export class MatSelectionList extends _MatSelectionListMixinBase implements CanDisableRipple,
+  AfterContentInit, ControlValueAccessor, OnDestroy, OnChanges {
 
   /** The FocusKeyManager which handles focus. */
   _keyManager: FocusKeyManager<MatListOption>;
@@ -429,8 +429,8 @@ export class MatSelectionList extends _MatSelectionListMixinBase implements Focu
   }
 
   /** Focuses the selection list. */
-  focus() {
-    this._element.nativeElement.focus();
+  focus(options?: FocusOptions) {
+    this._element.nativeElement.focus(options);
   }
 
   /** Selects all of the options. */

src/material/menu/menu-item.ts

@@ -97,11 +97,11 @@ export class MatMenuItem extends _MatMenuItemMixinBase
   }
 
   /** Focuses the menu item. */
-  focus(origin: FocusOrigin = 'program'): void {
+  focus(origin: FocusOrigin = 'program', options?: FocusOptions): void {
     if (this._focusMonitor) {
-      this._focusMonitor.focusVia(this._getHostElement(), origin);
+      this._focusMonitor.focusVia(this._getHostElement(), origin, options);
     } else {
-      this._getHostElement().focus();
+      this._getHostElement().focus(options);
     }
   }
 

src/material/menu/menu-trigger.ts

@@ -263,11 +263,11 @@ export class MatMenuTrigger implements AfterContentInit, OnDestroy {
    * Focuses the menu trigger.
    * @param origin Source of the menu trigger's focus.
    */
-  focus(origin: FocusOrigin = 'program') {
+  focus(origin: FocusOrigin = 'program', options?: FocusOptions) {
     if (this._focusMonitor) {
-      this._focusMonitor.focusVia(this._element, origin);
+      this._focusMonitor.focusVia(this._element, origin, options);
     } else {
-      this._element.nativeElement.focus();
+      this._element.nativeElement.focus(options);
     }
   }
 

src/material/radio/radio.ts

@@ -511,8 +511,8 @@ export class MatRadioButton extends _MatRadioButtonMixinBase
   }
 
   /** Focuses the radio button. */
-  focus(): void {
-    this._focusMonitor.focusVia(this._inputElement, 'keyboard');
+  focus(options?: FocusOptions): void {
+    this._focusMonitor.focusVia(this._inputElement, 'keyboard', options);
   }
 
   /**

src/material/select/select.ts

@@ -1042,8 +1042,8 @@ export class MatSelect extends _MatSelectMixinBase implements AfterContentInit,
   }
 
   /** Focuses the select element. */
-  focus(): void {
-    this._elementRef.nativeElement.focus();
+  focus(options?: FocusOptions): void {
+    this._elementRef.nativeElement.focus(options);
   }
 
   /** Gets the index of the provided option in the option list. */

src/material/slide-toggle/slide-toggle.ts

@@ -277,8 +277,8 @@ export class MatSlideToggle extends _MatSlideToggleMixinBase implements OnDestro
   }
 
   /** Focuses the slide-toggle. */
-  focus(): void {
-    this._focusMonitor.focusVia(this._inputElement, 'keyboard');
+  focus(options?: FocusOptions): void {
+    this._focusMonitor.focusVia(this._inputElement, 'keyboard', options);
   }
 
   /** Toggles the checked state of the slide-toggle. */

src/material/slider/slider.ts

@@ -295,8 +295,8 @@ export class MatSlider extends _MatSliderMixinBase
   }
 
   /** set focus to the host element */
-  focus() {
-    this._focusHostElement();
+  focus(options?: FocusOptions) {
+    this._focusHostElement(options);
   }
 
   /** blur the host element */
@@ -750,8 +750,8 @@ export class MatSlider extends _MatSliderMixinBase
    * Focuses the native element.
    * Currently only used to allow a blur event to fire but will be used with keyboard input later.
    */
-  private _focusHostElement() {
-    this._elementRef.nativeElement.focus();
+  private _focusHostElement(options?: FocusOptions) {
+    this._elementRef.nativeElement.focus(options);
   }
 
   /** Blurs the native element. */

tools/public_api_guard/material/button-toggle.d.ts

@@ -20,7 +20,7 @@ export declare class MatButtonToggle extends _MatButtonToggleMixinBase implement
     constructor(toggleGroup: MatButtonToggleGroup, _changeDetectorRef: ChangeDetectorRef, _elementRef: ElementRef<HTMLElement>, _focusMonitor: FocusMonitor, defaultTabIndex: string, defaultOptions?: MatButtonToggleDefaultOptions);
     _markForCheck(): void;
     _onButtonClick(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngOnDestroy(): void;
     ngOnInit(): void;
 }

tools/public_api_guard/material/button.d.ts

@@ -13,7 +13,7 @@ export declare class MatButton extends _MatButtonMixinBase implements OnDestroy,
     _getHostElement(): any;
     _hasHostAttributes(...attributes: string[]): boolean;
     _isRippleDisabled(): boolean;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngOnDestroy(): void;
 }
 

tools/public_api_guard/material/checkbox.d.ts

@@ -31,7 +31,7 @@ export declare class MatCheckbox extends _MatCheckboxMixinBase implements Contro
     _onInputClick(event: Event): void;
     _onInteractionEvent(event: Event): void;
     _onLabelTextChange(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngAfterViewChecked(): void;
     ngOnDestroy(): void;
     registerOnChange(fn: (value: any) => void): void;

tools/public_api_guard/material/chips.d.ts

@@ -66,7 +66,7 @@ export declare class MatChipInput implements MatChipTextControl, OnChanges {
     _focus(): void;
     _keydown(event?: KeyboardEvent): void;
     _onInput(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngOnChanges(): void;
 }
 
@@ -120,13 +120,13 @@ export declare class MatChipList extends _MatChipListMixinBase implements MatFor
     ngControl: NgControl);
     _allowFocusEscape(): void;
     _blur(): void;
-    _focusInput(): void;
+    _focusInput(options?: FocusOptions): void;
     _keydown(event: KeyboardEvent): void;
     _markAsTouched(): void;
     _setSelectionByValue(value: any, isUserInput?: boolean): void;
     protected _updateFocusForDestroyedChips(): void;
     protected _updateTabIndex(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngAfterContentInit(): void;
     ngDoCheck(): void;
     ngOnDestroy(): void;

tools/public_api_guard/material/core.d.ts

@@ -226,7 +226,7 @@ export declare class MatOptgroup extends _MatOptgroupMixinBase implements CanDis
     label: string;
 }
 
-export declare class MatOption implements AfterViewChecked, OnDestroy {
+export declare class MatOption implements FocusableOption, AfterViewChecked, OnDestroy {
     readonly _stateChanges: Subject<void>;
     readonly active: boolean;
     readonly disableRipple: boolean | undefined;
@@ -245,7 +245,7 @@ export declare class MatOption implements AfterViewChecked, OnDestroy {
     _handleKeydown(event: KeyboardEvent): void;
     _selectViaInteraction(): void;
     deselect(): void;
-    focus(): void;
+    focus(_origin?: FocusOrigin, options?: FocusOptions): void;
     getLabel(): string;
     ngAfterViewChecked(): void;
     ngOnDestroy(): void;

tools/public_api_guard/material/expansion.d.ts

@@ -89,7 +89,7 @@ export declare class MatExpansionPanelHeader implements OnDestroy, FocusableOpti
     _keydown(event: KeyboardEvent): void;
     _showToggle(): boolean;
     _toggle(): void;
-    focus(origin?: FocusOrigin): void;
+    focus(origin?: FocusOrigin, options?: FocusOptions): void;
     ngOnDestroy(): void;
 }
 

tools/public_api_guard/material/input.d.ts

@@ -41,7 +41,7 @@ export declare class MatInput extends _MatInputMixinBase implements MatFormField
     protected _isTextarea(): boolean;
     _onInput(): void;
     protected _validateType(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngDoCheck(): void;
     ngOnChanges(): void;
     ngOnDestroy(): void;

tools/public_api_guard/material/list.d.ts

@@ -65,7 +65,7 @@ export declare class MatNavList extends _MatListMixinBase implements CanDisableR
     ngOnDestroy(): void;
 }
 
-export declare class MatSelectionList extends _MatSelectionListMixinBase implements FocusableOption, CanDisableRipple, AfterContentInit, ControlValueAccessor, OnDestroy, OnChanges {
+export declare class MatSelectionList extends _MatSelectionListMixinBase implements CanDisableRipple, AfterContentInit, ControlValueAccessor, OnDestroy, OnChanges {
     _keyManager: FocusKeyManager<MatListOption>;
     _onTouched: () => void;
     _value: string[] | null;
@@ -83,7 +83,7 @@ export declare class MatSelectionList extends _MatSelectionListMixinBase impleme
     _reportValueChange(): void;
     _setFocusedOption(option: MatListOption): void;
     deselectAll(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngAfterContentInit(): void;
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;

tools/public_api_guard/material/menu.d.ts

@@ -88,7 +88,7 @@ export declare class MatMenuItem extends _MatMenuItemMixinBase implements Focusa
     _getHostElement(): HTMLElement;
     _getTabIndex(): string;
     _handleMouseEnter(): void;
-    focus(origin?: FocusOrigin): void;
+    focus(origin?: FocusOrigin, options?: FocusOptions): void;
     getLabel(): string;
     ngOnDestroy(): void;
 }
@@ -132,7 +132,7 @@ export declare class MatMenuTrigger implements AfterContentInit, OnDestroy {
     _handleKeydown(event: KeyboardEvent): void;
     _handleMousedown(event: MouseEvent): void;
     closeMenu(): void;
-    focus(origin?: FocusOrigin): void;
+    focus(origin?: FocusOrigin, options?: FocusOptions): void;
     ngAfterContentInit(): void;
     ngOnDestroy(): void;
     openMenu(): void;

tools/public_api_guard/material/radio.d.ts

@@ -26,7 +26,7 @@ export declare class MatRadioButton extends _MatRadioButtonMixinBase implements
     _markForCheck(): void;
     _onInputChange(event: Event): void;
     _onInputClick(event: Event): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
     ngOnInit(): void;

tools/public_api_guard/material/select.d.ts

@@ -76,7 +76,7 @@ export declare class MatSelect extends _MatSelectMixinBase implements AfterConte
     _onBlur(): void;
     _onFocus(): void;
     close(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngAfterContentInit(): void;
     ngDoCheck(): void;
     ngOnChanges(changes: SimpleChanges): void;

tools/public_api_guard/material/slide-toggle.d.ts

@@ -26,7 +26,7 @@ export declare class MatSlideToggle extends _MatSlideToggleMixinBase implements
     _onDragStart(): void;
     _onInputClick(event: Event): void;
     _onLabelTextChange(): void;
-    focus(): void;
+    focus(options?: FocusOptions): void;
     ngAfterContentInit(): void;
     ngOnDestroy(): void;
     registerOnChange(fn: any): void;